Les blocs typés : pourquoi une page n'est jamais du HTML libre

S’il ne fallait retenir qu’une convention de cette base, ce serait celle-ci : une page n’est jamais du HTML libre. Une page, c’est un fichier JSON contenant une liste de blocs typés — rien d’autre. Pas de balises à la main, pas de mise en page improvisée, pas d’exception « juste pour cette fois ».

Six blocs, pas un de plus

Chaque bloc déclare son type via un champ template :

Template	Rôle
hero_v1	L’entrée de page : titre, sous-titre, bouton d’action optionnel
rich_text_v1	Du texte riche en Markdown
faq_v1	Questions/réponses
articles_grid_v1	Les derniers articles du blog, en grille
cta_band_v1	Un bandeau d’appel à l’action
image_text_v1	Image et texte côte à côte

Et la règle qui donne sa force au système : un template inconnu casse le build. Une faute de frappe dans template, un bloc inventé, un champ manquant — le site refuse de se générer. L’erreur reste dans le dépôt, jamais en production.

Trois sources de vérité, une seule définition

Un bloc existe simultanément dans trois fichiers, et les trois doivent décrire exactement la même chose :

1. public/admin/config.yml — ce que Sveltia laisse éditer dans l’admin ;
2. src/content/config.ts — ce que Zod valide au moment du build ;
3. src/lib/blocks.ts — ce qu’Astro sait rendre en HTML.

La dérive silencieuse entre ces trois fichiers est le bug classique d’un duo CMS/générateur statique : un champ éditable mais rejeté au build, ou validé mais jamais affiché. C’est pourquoi audit:cms compare mécaniquement les trois sources — ajouter un champ dans une seule d’entre elles fait échouer l’audit, donc la CI, comme décrit dans le tribunal qualité.

block_key : l’identité stable d’un bloc

Chaque bloc porte un block_key unique dans sa page et stable dans le temps. C’est lui qui permet de suivre un bloc à travers les diffs git, de le cibler dans un message d’erreur (« le CTA du bloc home-hero est cassé »), et demain de lui rattacher des mesures de performance. On ne renomme pas un block_key sans raison, exactement comme on ne renomme pas une clé primaire.

Quatre statuts, un seul rendu en production

Pages et articles portent un statut : draft, review, published ou archived. Seul published est rendu en production. Un brouillon commité par erreur ne fuite pas ; un contenu archivé disparaît du site mais reste dans l’historique git. La gouvernance de ces transitions — qui publie, qui archive — relève des règles décrites dans l’article sur la gouvernance.

Ce que la contrainte achète

Le HTML libre est plus rapide le premier jour, et plus coûteux tous les jours suivants. Les blocs typés achètent trois garanties : une cohérence visuelle totale (un bloc a un seul rendu, partout), une qualité SEO vérifiable (les champs obligatoires sont validés, pas espérés), et une éditabilité par agent sans risque (une structure prévisible se manipule sans casser la mise en page).

Besoin d’un nouveau type de bloc ? C’est une évolution du code, pas du contenu : on l’ajoute une fois dans les trois sources, l’audit valide la cohérence, et il devient disponible pour toutes les pages — de ce site et de tous les sites clonés.