Construire un thème de zéro

Les thèmes Chinaski sont un répertoire de fichiers Template Toolkit : quelques coquilles HTML plus un partial head, et chaque type de block se rend via son propre template. Ce guide parcourt la fabrication du vôtre de bout en bout : scaffolding, écriture des templates, câblage des blocks et menus, et tests.

Commencer : trois façons

• Clonez un thème de départ enregistré sur l'écran Themes : le nouveau slug reçoit une copie complète à éditer.
• Générez avec Claude: le panneau Themes prend un nom, une *Design Brief* facultative (choisissez un design de référence précédemment téléversé, ou en téléversez un au vol) et éventuellement un Design Intent d'un paragraphe. *Create Theme Scaffold* clone les fichiers de départ, puis montre un prompt prêt à copier nommant votre thème, votre brief et votre intention ; remettez-le à votre assistant connecté via MCP, qui lira le guide de thème intégré et écrira les fichiers pour vous.
• Manuellement: copiez builder/site_templates/ vers builder/themes/<your-slug>/ et modifiez les copies selon le même contrat ci-dessous.

L'une ou l'autre route crée le slug et l'enregistre dans la table des thèmes ; l'écran Themes montre quel thème est actuellement actif et seuls les thèmes non actifs peuvent être supprimés.

Les fichiers qu'un thème porte

La carte des fichiers du thème par défaut est sur la page *Letterbox* ; chaque template qui s'y trouve (_head.tt, _header.tt, _footer.tt, page.tt, post.tt, blog_index.tt, plus 404.tt, documents.tt, search.tt, offline.tt) appartient à un thème. Votre thème de remplacement recrée n'importe quel sous-ensemble par nom ; les templates page.tt/post.tt/blog_index.tt sont ce que le builder cherche.

Déclarez les emplacements de menu en écrivant un commentaire marqueur en haut d'un template : [%# MENU_SLOT: header %]. L'écran Navigation repère chaque emplacement déclaré dans votre thème et le propose quand vous créez un élément de nav.

Le contrat du renderer

builder/build.pl lit la base de données SQLite et fait passer chaque page et post publiés par Template Toolkit, en écrivant le HTML résultant sous output/<lang>/ :

• rend les pages, posts, les index blog + catégorie, le flux RSS, le sitemap, le robots.txt et le 404
• copie public/media/ par langue
• nettoie la sortie non écrite lors de cette exécution (éléments supprimés, dépubliés, hors fenêtre)
• respecte la promotion guard, le budget d'écriture et le timeout global du build

Les échecs de rendu de template n'interrompent pas un build ; le template en échec est consigné et le build continue (visible via Build history / dashboard).

Template Toolkit en bref

Utilisez | html pour tout champ contrôlé par l'utilisateur et | uri pour les composants d'URL. IF/UNLESS/FOREACH couvre les boucles (loop.index, loop.count, loop.last). Les includes partagent les partials intégrés par le stash ([% INCLUDE '_head.tt' %]).

Chaque template de site reçoit des variables documentées : page.tt reçoit title, body, slug, language, champs meta, champs OG, featured image, et les réglages au niveau du site comme site_name, url_base ; post.tt reçoit en plus excerpt, author, category, tags, custom fields ; blog_index.tt reçoit le listing des posts et l'objet de pagination. La documentation du thème intégré liste les tables de variables complètes par template et les détails.

Les blocks

builder/block_templates/*.tt (un fichier par type de block) sont du markup indépendant des thèmes, donc les thèmes stylent les blocks par nom de classe plutôt que par markup. La feuille de style du thème par défaut (_head.tt) implémente chaque classe wrapper/inner documentée dans la référence de classes des blocks intégrés ; votre _head.tt doit couvrir le même contrat (sinon les blocks se rendent sans style). Tout {{block:name​}} en ligne dans un corps arrive déjà rendu dans la variable body de votre template ; coordonnez les classes CSS plutôt que de rescanner les marqueurs.

Tester tant que votre thème est inactif

• Preview: le lien de prévisualisation de l'écran Themes rend des vues d'exemple de page, post et blog depuis le thème en cours sans toucher au site en ligne (avec de vraies données de nav de la langue par défaut).
• Build réel: cliquez sur Build (ou lancez perl builder/build.pl), consultez le dashboard et le Build history pour la sortie complète du build et les noms des templates en échec.
• Itérations sûres: lancez le builder avec CHINASKI_OUTPUT=/tmp/preview pour écrire dans un autre répertoire et ne pas toucher à votre site en ligne.

Règles de sécurité à respecter en construisant

• échappez les scalaires contrôlés par l'utilisateur avec | html ; exceptions : les corps de pages/posts (bruts intentionnellement) et le JSON-LD qui vous est passé pré-échappé
• utilisez | uri sur les composants d'URL construits à partir d'entrées utilisateur ; ne concaténez jamais de valeurs brutes dans href/src
• les valeurs de champs de block viennent de formulaires d'admin, toujours non fiables, échappez-les
• le contenu des snippets est verbatim ; auditez qui peut éditer les snippets (cette permission est à un pas de l'exécution de JavaScript tiers arbitraire sur votre site public)
• minimisez les blocks <script> en ligne : le CSP du site statique les autorise aujourd'hui, mais chaque script en ligne supplémentaire élargit la surface XSS si une injection dans un corps arrive jamais

Le livrer

Quand le nouveau thème paraît correct en prévisualisation, activez-le sur Themes, l'ancien thème reste disponible ; la suppression d'un thème n'est permise que pour les non actifs. Changer le thème actif invalide l'état du build incrémental, donc le build suivant le changement est un build complet, et la sortie en ligne utilisera de façon constante les nouveaux templates.