Fichiers Template

Un thème Chinaski est un répertoire de fichiers Template Toolkit que le builder statique rend en chaque page, post, index de blog, flux et page d'erreur. Cette page couvre l'ensemble de templates et les règles de recherche ; les templates de blocks et les variables de template ont chacun davantage de profondeur sur les pages liées, et la référence complète des variables se trouve dans la doc intégrée d'authoring de thème de l'admin (Admin → Docs).

Le répertoire de templates du site

Les templates du site vivent dans builder/site_templates/ (ou une surcharge de répertoire de thème, voir plus bas). Un fichier par sortie de forme page, plus les optionnels :

Fichier	Rendu comme
`page.tt`	chaque page publiée (défaut)
`post.tt`	chaque post publié
`blog_index.tt`	les listings de blog paginés (+ archives par catégorie/auteur via le renderer partagé)
`landing.tt`	les pages qui sélectionnent le template landing
`404.tt`	la page 404 par langue
`offline.tt`	page de repli hors ligne de la PWA
`_head.tt`	partial `<head>` (meta tags, canonique, JSON-LD)
`_header.tt` / `_footer.tt`	partials header/footer du site
`_cookie_notice.tt`	bannière de consentement optionnelle
`_sidebar.tt`, `_meta_tags.tt`, `_password_gate.tt`	autres partials partagés
`<n'importe quoi>.tt`	toute page qui sélectionne ce template par nom

Conventions : les fichiers commençant par _ sont des partials : ils ne rendent jamais comme pages autonomes. Exigences « zero-viable » : les pages peuvent taper un nom de template personnalisé (landing.tt etc.) et le builder le prend dans ce répertoire (ou dans votre thème actif s'il y réside en premier).

Le squelette d'un starter est minimal :

<!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 seule non-échappée délibérée : [% body %] émet volontairement le HTML stocké ; les auteurs de pages sont la frontière de confiance ; n'étendez pas la sortie brute à d'autres champs.

Recherche et repli (les thèmes ajustent le défaut)

Quand un thème non-défaut est actif, son répertoire est recherché en premier et builder/site_templates/ en second, de sorte qu'un thème n'a besoin que de livrer ce qu'il personnalise ; les fichiers manquants retombent automatiquement sur les intégrés plutôt que de faire échouer un build.

Dupliquer (fork) _head.tt plutôt que le réécrire est recommandé : il émet déjà tout le jeu de meta (canonique, OG/Twitter, hreflang, JSON-LD, noindex, et analytique avec gate de consentement) et le builder calcule à la main ces valeurs pour le stash du template.

Ce que chaque build rend

Pour chaque langue configurée le builder rend : les pages publiées, les posts publiés, l'index de blog paginé, les archives par catégorie, le flux de posts (RSS), le sitemap, robots.txt, et la page 404. La sortie est écrite fichier par fichier (avec un plafond d'horloge de 30 minutes et un budget d'écriture de 2 GiB qui avortent en sécurité au-delà de la limite), et tout fichier périmé d'une exécution précédente est retiré.

Un échec de rendu template n'arrête pas le build : l'échec est consigné dans le log de build et la boucle continue. Le tableau de bord nomme les premiers templates en échec ; le premier endroit où regarder en cas de debug est l'écran builds.

L'échappatoire : les templates par page

L'éditeur de chaque page a un menu déroulant de template peuplé automatiquement depuis les fichiers .tt non-partials du répertoire standard plus le répertoire du thème actif, et il garde toujours le template actuellement posé de la page dans la liste même si ce fichier appartient à un thème inactif, pour qu'une re-sauvegarde de routine ne puisse pas échanger des templates en silence.

Snippets (injections avec une piste d'audit)

Un snippet est un morceau de HTML contrôlé à la main inséré verbatim au bas de <head> ou avant </body> : analytique, precedes, tags de vérification. Ils peuvent être globaux (injectés sur tout le site) ou attachés à des pages/posts individuels (aussi par case à cocher dans ces éditeurs). Comme le contenu de snippet est injecté verbatim, quiconque a le droit d'éditer des snippets peut installer du JavaScript arbitraire sur chaque page ; traitez-le comme un accès serveur.

Tester votre thème

Éditez les fichiers .tt dans le répertoire du thème (ou site_templates/ pour les retouches noyau).
Cliquez Build sur le tableau de bord (ou lancez le builder à la main).
Les erreurs incluent le nom du template en échec et une raison ; le log complet est dans l'écran Builds.

Le système de build attrape les erreurs de template même dans la validation ; les échecs consignent le fichier et l'erreur, pas juste un « done » indifférencié.

Règles de sécurité

Échappez tout ce qui est contrôlé par l'utilisateur avec | html ; les exceptions intentionnelles sont body (rich-text brut par conception) et json_ld (pré-sérialisé, </script> déjà neutralisé).
| uri pour encoder les composants d'URL ; ne concaténez jamais de valeurs brutes dans des hrefs ou des attributs.
Scripts inline minimaux seulement : chaque script inline élargit la surface casse-vitre.
Les valeurs de champs de block arrivent non-échappées des formulaires admin ; échappez-les.
L'accès aux snippets égale un accès serveur : quiconque peut éditer des snippets peut exécuter du contenu sur chaque page.