Arquivos de Template

Um tema Chinaski é um diretório de arquivos Template Toolkit que o builder estático renderiza em cada página, post, índice de blog, feed, e página de erro. Esta página cobre o conjunto de templates e as regras de busca; templates de bloco e variáveis de template ganham mais profundidade em páginas vinculadas cada um, e a referência completa de variáveis vive no doc embutido de Theme Authoring do admin (Admin → Docs).

O diretório de templates de site

Os templates de site vivem em builder/site_templates/ (ou numa sobrescrita de diretório de tema : veja abaixo). Um arquivo por saída em forma de página, mais os opcionais:

Arquivo	Renderizado como
`page.tt`	cada página publicada (padrão)
`post.tt`	cada post publicado
`blog_index.tt`	as listagens paginadas de blog (+ arquivos por categoria/autor via o renderizador compartilhado)
`landing.tt`	páginas que selecionam o template de landing
`404.tt`	a página 404 por idioma
`offline.tt`	página de fallback offline da PWA
`_head.tt`	partial de `<head>` (meta tags, canônica, JSON-LD)
`_header.tt` / `_footer.tt`	partials de header/rodapé do site
`_cookie_notice.tt`	banner de consentimento opcional
`_sidebar.tt`, `_meta_tags.tt`, `_password_gate.tt`	outros partials compartilhados
`<qualquer-coisa>.tt`	qualquer página que selecione aquele template pelo nome

Convenções: arquivos começando com _ são partials : nunca são renderizados como páginas independentes. Requisitos de viabilidade zero: páginas podem digitar um nome de template personalizado (landing.tt etc.) e o builder o pega deste diretório (ou do seu tema ativo, se ele ali viver primeiro).

O esqueleto de um iniciador é mínimo:

<!DOCTYPE html>
<html lang="[% lang | html %]" dir="[% dir %]">
<head>
  [% INCLUDE '_head.tt' %]
</head>
<body>
  [% INCLUDE '_header.tt' %]
  <main>[% title | html %][% body %]</main>
  [% INCLUDE '_footer.tt' %]
</body>
</html>

O único não-escapamento deliberado: [% body %] emite HTML armazenado de propósito : os autores de páginas são a fronteira de confiança; não estenda a saída crua a outros campos.

Busca e fallback (temas ajustam o padrão)

Quando um tema não padrão está ativo, seu diretório é buscado primeiro e builder/site_templates/ em segundo : de modo que um tema só precisa embarcar o que personaliza; arquivos faltantes fazem fallback aos built-ins automaticamente em vez de falhar um build.

Forkar _head.tt em vez de reescrevê-lo é recomendado: ele já emite o conjunto completo de metas (canônica, OG/Twitter, hreflang, JSON-LD, noindex, e analytics com portão de consentimento) e o builder calcula à mão esses valores para o stash do template.

O que cada build renderiza

Para cada idioma configurado o builder renderiza: páginas publicadas, posts publicados, o índice de blog paginado, arquivos por categoria, o feed de posts (RSS), o sitemap, robots.txt, e a página 404. A saída é escrita arquivo por arquivo (com um teto de wall-clock de 30 minutos e um orçamento de escrita de 2 GiB que abortam com segurança além do limite), e quaisquer arquivos obsoletos de uma execução anterior são removidos.

Uma falha de renderização de template não para o build: a falha é registrada no build log e o loop continua. O dashboard nomeia os primeiros templates que falharam; o primeiro lugar a se olhar na depuração é a tela de builds.

A válvula de escape: templates por página

O editor de cada página tem um dropdown de template povoado automaticamente a partir dos arquivos .tt não-partial no diretório padrão mais o diretório do tema ativo : e ele sempre mantém o template definido atual da página na lista, mesmo que aquele arquivo pertença a um tema inativo, de modo que uma ressalva rotineira não pode trocar templates silenciosamente.

Snippets (injeções com uma trilha de auditoria)

Um snippet é um pedaço controlado à mão de HTML inserido verbatim no fundo de <head> ou antes de </body> : analytics, verification tags. Podem ser globais (injetados no site todo) ou anexados a páginas/posts individuais (também por caixote naqueles editores). Como o conteúdo de snippet é injetado verbatim, qualquer um com direitos de editar snippets pode instalar JavaScript arbitrário em cada página : trate-o como acesso ao servidor.

Testando seu tema

Edite os arquivos .tt no diretório do tema (ou site_templates/ para ajustes ao núcleo).
Clique em Build no dashboard (ou execute o builder à mão).
Os erros incluem o nome do template que falhou e um motivo; o log completo está na tela de Builds.

O sistema de build apanha erros de template até na validação : as falhas registram o arquivo e o erro, não apenas um “feito” geral.

Regras de segurança

Escape tudo controlado por usuário com | html; as exceções intencionais são body (rich-text cru por design) e json_ld (pré-serializado, </script> já neutralizado).
| uri para codificar componentes de URL : nunca concatene valores crus em hrefs ou atributos.
Apenas scripts inline mínimos : cada script inline alarga a superfície de quebra-do-vidro.
Valores de campos de bloco chegam de formulários de admin sem escape; escape-os.
Acesso a snippet equivale a acesso ao servidor: quem quer que possa editar snippets pode executar conteúdo em cada página.