Construir um Tema do Zero

Os temas Chinaski são um diretório de arquivos Template Toolkit: um par de shells HTML mais um partial de head, e cada tipo de bloco renderiza via seu próprio template. Este guia percorre a criação do seu tema do início ao fim: scaffolding, escrever templates, ligar blocos e menus, e testar.

Começando: três caminhos

Clone um tema inicial registrado na tela de Themes: o novo slug ganha uma cópia completa para editar.
Gere com o Claude: o painel de Themes toma um nome, um Design Brief opcional (escolha um design de referência previamente enviado, ou faça upload de um inline) e opcionalmente um parágrafo único de Design Intent. Create Theme Scaffold clona os arquivos de partida, então mostra um prompt pronto-para-copiar nomeando seu tema, brief e intent; entregue-o ao seu assistente conectado por MCP, que lerá o guia de temas embutido e escreverá os arquivos por você.
Manualmente: copie builder/site_templates/ para builder/themes/<seu-slug>/ e edite as cópias para o mesmo contrato abaixo.

Qualquer rota cria o slug e o registra na tabela de temas; a tela de Themes mostra qual tema está atualmente ativo e apenas temas não ativos podem ser apagados.

Os arquivos que um tema carrega

O mapa de arquivos do tema padrão está na página da Letterbox: cada template ali (_head.tt, _header.tt, _footer.tt, page.tt, post.tt, blog_index.tt, mais 404.tt, documents.tt, search.tt, offline.tt) pertence a um tema. Seu tema de substituição re-cria qualquer subconjunto pelo nome; os templates em page.tt/post.tt/blog_index.tt são o que o builder procura.

Declare slots de menu escrevendo um comentário-marcador no topo de um template: [%# MENU_SLOT: header %]. A tela de Navigation pega todo slot declarado do seu tema e o oferece quando você cria um item de navegação.

O contrato do renderizador

builder/build.pl lê o banco de dados SQLite e passa cada página e post publicados pelo Template Toolkit, escrevendo o HTML resultante sob output/<lang>/:

Renderiza páginas, posts, os índices de blog + categoria, o feed RSS, sitemap, robots.txt e o 404
Copia public/media/ em cada idioma
Limpa a saída não escrita nesta execução (itens apagados, não publicados, fora de janela)
Honra o promotion guard, o orçamento de escrita, e o timeout geral do build

Falhas de renderização de template não abortam um build: o template que falhou é registrado e o build continua (visível via Build history / dashboard).

Template Toolkit em resumo

Use | html para qualquer campo controlado por usuário e | uri para componentes de URL. IF/UNLESS/FOREACH cobre loops (loop.index, loop.count, loop.last). Includes compartilham os partials embutidos pelo stash ([% INCLUDE '_head.tt' %]).

Cada template de site recebe variáveis documentadas: page.tt obtém título, corpo, slug, idioma, campos de meta, campos OG, imagem destacada, e configurações de nível de site como site_name, url_base; post.tt adicionalmente recebe excerpt, autor, categoria, tags, campos personalizados; blog_index.tt obtém a listagem de posts e o objeto de paginação. Os docs de tema embutidos listam as tabelas completas de variáveis por template e os detalhes.

Blocos

builder/block_templates/*.tt, um arquivo por tipo de bloco, é marcação independente de tema, de modo que temas estilizam blocos por nome de classe em vez de por marcação. A stylesheet do tema padrão (_head.tt) implementa toda classe wrapper/inner documentada na referência embutida de classes de blocos; o seu _head.tt deve cobrir o mesmo contrato (ou blocos renderizam sem estilo). Qualquer {{block:name}} inline num corpo chega já renderizado na variável de corpo do seu template; coordene as classes CSS em vez de re-escanear marcadores.

Testando enquanto um tema inativo é seu

Preview: o link de preview da tela de Themes renderiza visões de exemplo de página, post e blog a partir do tema em andamento, sem tocar no site ao vivo (com dados reais de navegação do idioma padrão).
Build real: clique em Build (ou execute perl builder/build.pl), cheque o dashboard e o Build history por saída completa de build e nomes de templates falhos.
Iterações seguras: execute o builder com CHINASKI_OUTPUT=/tmp/preview para escrever a outro diretório e não tocar no seu site ao vivo.

Regras de segurança para construir

Escape escalares controlados por usuário com | html. Exceções: corpos de página/post (intencionalmente crus) e JSON-LD entregue a você pré-escapado
Use | uri em componentes de URL construídos de entrada do usuário; nunca concatene valores crus em href/src
Valores de campos de bloco vêm de formulários de admin, mas ainda são não confiáveis: escape-os
O conteúdo de snippet é verbatim; audite quem pode editar snippets (essa permissão está a um passo de executar JavaScript arbitrário de terceiros no seu site público)
Minimize blocos <script> inline: a CSP do site estático os permite hoje, mas cada script inline adicional alarga a superfície de XSS se uma injeção de corpo um dia aterrissar

Colocando no ar

Quando o novo tema parece certo no preview, ative-o em Themes: o tema antigo permanece disponível; apagar um tema é permitido apenas para os não ativos. Trocar o tema ativo invalida o estado de build incremental, de modo que o próximo build após a troca é um completo, e a saída ao vivo usará consistentemente os novos templates.