O Tema Letterbox
A Letterbox é o tema padrão que embarca com o slug default. Seus templates vivem em builder/site_templates/ : um conjunto de páginas Template Toolkit compondo cada URL pública mais sua stylesheet inteira : e esta referência mapeia todos eles para que você possa cloná-los ou substituí-los com confiança.
Como o tema padrão funciona no disco
Os templates da Letterbox sentam-se em site_templates/ diretamente (diferente dos temas clonados, que vivem sob builder/themes/<name>). Quando o seu tema ativo é a Letterbox, é de lá que o builder lê e onde sua fingerprint de build tranca as mudanças de tema; quando você ativa um tema clonado em vez disso, o próprio diretório dele sob builder/themes/ é usado.
Os únicos slots de menu que o tema padrão declara são header e footer, com uma árvore de dropdown de um nível suportada no header.
Os templates
| Arquivo | Linhas | O que renderiza |
|---|---|---|
_head.tt | ~1700 | O head de cada página: a stylesheet completa, marcação/estilos do aviso de cookies, skip-link, loader de analytics inline, estilos do portão de senha, mais o include de meta-tags |
_meta_tags.tt | ~60 | As meta tags Open Graph / Twitter / canônica / hreflang / paginação |
_header.tt | ~66 | Barra de logo/identidade com menu de topo nível + dropdowns |
_footer.tt | ~20 | Menu de rodapé, copyright, e (quando há posts) link RSS |
page.tt | ~64 | Uma página de conteúdo |
post.tt | ~120 | Um post de blog: heading, linha de meta, tags, chip de categoria, tempo de leitura, blocos |
blog_index.tt | ~115 | Índice de blog paginado com cards de imagem destacada |
_sidebar.tt | ~40 | Widgets de sidebar (blurb sobre, posts recentes, categorias) |
documents.tt | ~47 | A página de documentos/downloads |
search.tt | ~100 | Resultados de busca de site apoiados em search-index.json |
404.tt | ~20 | A página “Page not found” |
offline.tt | ~20 | O fallback offline da PWA |
landing.tt + _landing_block_styles.tt | 35 + ~450 | Um layout de landing page com estilos de bloco extras |
raw.tt | ~12 | Passagem apenas-de-corpo para páginas que precisam de controle total de marcação |
_cookie_notice.tt | ~24 | O banner fixo de cookies |
_password_gate.tt | ~75 | Portão de senha no lado do cliente para conteúdo protegido |
Onde o estilo vive
Todo o styling do visual padrão é inline no _head.tt : não há arquivo CSS separado. Header, hero, tipografia de página e de post, cards de blog, widgets de sidebar, tabelas, aviso de cookies, e as classes wrapper de cada tipo de bloco (.cta-block, .gallery-block, .accordion-block, e assim por diante) estão definidas ali.
Aquele arquivo é a API visual do tema: os temas de qualquer página podem declarar blocos esperando aqueles nomes de classe. As tabelas wrapper/inner da documentação embutida de blocos são exatamente o que a Letterbox implementa para cada tipo. Se você escreve o próprio tema, replique esse contrato : ao mínimo, cada wrapper de bloco mais seu tratamento de heading/corpo precisa de cobertura, senão os blocos ainda renderizam mas parecem sem estilo.
Opções que mudam a saída da Letterbox
- Slots de menu : declare slots de menu adicionais no seu tema (ou clone o tema) para adicionar mais que header/rodapé; o padrão tem só os dois.
- O template de landing page : uma página pode sobrescrever seu template com um nome de arquivo que inclua a extensão
.tt(por exemplolanding.ttouraw.tt); landing.tt traz os próprios estilos de bloco. - Saída de PWA : habilite a PWA e
offline.html/sw.js/manifest.jsonse juntam à saída por idioma. - Template RAW : uma página definida como
raw.ttrecebe o corpo sozinho sem andaimes de tema de nenhuma forma. - Analytics e consentimento : o script GA4/GTM no
_head.ttcarrega apenas quando o aviso de cookies registra o consentimento (ou pula quando nenhum aviso está ativo), e nunca carrega de todo no modo air-gap.
Clonando para fazer Letterbox-plus
A tela de Templates oferece Clone (a partir do tema inicial configurado, com a Letterbox como fallback deste) e um painel Generate with Claude que do mesmo modo levanta um tema novo primeiro, então devolve um prompt ao seu assistente para o trabalho de templing. Os templates de um tema podem ser sobrescritos diretamente no editor de temas; seu conteúdo é escaneado por segurança e validado sintaticamente no lado do servidor antes de ser aceito. Apagar um tema é permitido apenas para os temas não ativos.
O fundamento
A Letterbox é deliberamente mínima mas completa : renderiza cada artefato de saída do CMS (telas embutidas incluídas) com classes completamente soletadas e templates pequenos. Cloná-la é o ponto de partida pretendido de temas personalizados; tudo de que você precisa para isso está no doc de autoria de temas e neste mapa de arquivos.