Archivos de Plantilla

Un theme de Chinaski es un directorio de archivos Template Toolkit que el builder estático renderiza en cada página, post, índice de blog, feed y página de error. Esta página cubre el conjunto de templates y las reglas de búsqueda; las block templates y las variables de template tienen mayor profundidad en las páginas enlazadas, y la referencia completa de variables vive en el doc integrado de Theme Authoring del admin (Admin → Docs).

El directorio de site templates

Las site templates viven en builder/site_templates/ (o en un override de directorio de theme: ver abajo). Un archivo por cada salida con forma de página, más opcionales:

Archivo	Renderizado como
page.tt	cada página publicada (por defecto)
post.tt	cada post publicado
blog_index.tt	los listados paginados del blog (+ archivos por categoría/autor vía el renderer compartido)
landing.tt	páginas que seleccionan la template landing
404.tt	la página 404 por idioma
offline.tt	página de fallback offline de la PWA
_head.tt	parcial de <head> (meta tags, canonical, JSON-LD)
_header.tt / _footer.tt	parciales de header/footer del site
_cookie_notice.tt	banner de consentimiento opcional
_sidebar.tt, _meta_tags.tt, _password_gate.tt	otros parciales compartidos
<anything>.tt	cualquier página que seleccione esa template por nombre

Convenciones: los archivos que empiezan con _ son parciales: nunca se renderizan como páginas independientes. Requisitos cero-viables: las páginas pueden escribir un nombre de template personalizado (landing.tt etc.) y el builder lo toma de este directorio (o de tu theme activo si vive allí primero).

El esqueleto inicial es 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>

La única omisión de escape deliberada: [% body %] emite HTML almacenado a propósito: los autores de páginas son el límite de confianza; no extiendas la salida raw a otros campos.

Búsqueda y fallback (los themes ajustan el valor por defecto)

Cuando hay un theme no predeterminado activo, su directorio se busca primero y builder/site_templates/ segundo: así que un theme solo necesita incluir lo que personaliza; los archivos faltantes hacen fallback a los integrados automáticamente en lugar de fallar un build.

Se recomienda hacer fork de _head.tt en lugar de reescribirlo: ya emite el conjunto completo de metas (canonical, OG/Twitter, hreflang, JSON-LD, noindex, y analytics con control de consentimiento) y el builder precalcula esos valores para el stash de la template.

Qué renderiza cada build

Para cada idioma configurado el builder renderiza: páginas publicadas, posts publicados, el índice de blog paginado, archivos por categoría, el feed de posts (RSS), el sitemap, robots.txt y la página 404. La salida se escribe archivo por archivo (con un techo de reloj de 30 minutos y un presupuesto de escritura de 2 GiB que abortan de forma segura al pasar el límite), y cualquier archivo obsoleto de una corrida anterior se elimina.

Un fallo de renderizado de template no detiene el build: el fallo se registra en el log de build y el loop continúa. El dashboard nombra las primeras templates que fallan; el primer lugar que hay que mirar al depurar es la pantalla de builds.

La vía de escape: templates por página

El editor de cada página tiene un dropdown de templates poblado automáticamente a partir de los archivos .tt no-parciales del directorio estándar más el directorio del theme activo: y siempre mantiene en la lista la template actualmente definida de la página incluso si ese archivo pertenece a un theme inactivo, para que un re-guardado de rutina no intercambie templates silenciosamente.

Snippets (inyecciones con pista de auditoría)

Un snippet es un fragmento de HTML controlado a mano insertado textualmente al final de <head> o antes de </body>: analytics, precedes, etiquetas de verificación. Pueden ser globales (inyectados en todo el site) o adjuntarse a páginas/posts individuales (también por casilla en esos editores). Como el contenido de los snippets se inyecta textualmente, cualquiera con derechos de edición de snippets puede instalar JavaScript arbitrario en cada página: trátalo como acceso al servidor.

Probar tu theme

1. Edita los archivos .tt en el directorio del theme (o site_templates/ para ajustes del core).
2. Haz clic en Build en el dashboard (o ejecuta el builder a mano).
3. Los errores incluyen el nombre de la template que falla y una razón; el log completo está en la pantalla Builds.

El sistema de build atrapa los errores de template incluso en la validación: los fallos registran el archivo y el error, no solo un genérico "done".

Reglas de seguridad

• Escapa todo dato controlado por el usuario con | html; las excepciones intencionales son body (rich-text raw por diseño) y json_ld (pre-serializado, </script> ya neutralizado).
• | uri para codificar componentes de URL: nunca concatenes valores raw en hrefs ni atributos.
• Solo scripts inline mínimos: cada script inline amplía la superficie de break-glass.
• Los valores de campos de blocks llegan sin escapar de los formularios del admin; escápalos.
• El acceso a snippets equivale a acceso al servidor: quien pueda editar snippets puede ejecutar contenido en cada página.