Front matter

Le front matter est le bloc de métadonnées lisible par la machine au début de chaque fichier Markdown. La gouvernance définit les champs que la rédaction peut utiliser; l’architecture définit comment les gabarits consomment ces champs.

Utilisez Gouvernance du site > Contenu > Front matter pour les règles de rédaction. Utilisez cette page pour ajouter un comportement de gabarit, des archétypes de section ou des index pilotés par les métadonnées.

Métadonnées de page#

Chaque page de documentation commence avec une forme stable :

title: "Anchor index"
date: 2026-08-11
lastmod: 2026-08-17
description: "A labeled row of compact links that jumps to repeated page sections"
weight: 10
related:
  - /docs/site-implementation/components/filter-row/

Les gabarits utilisent ces champs pour les titres, les descriptions, le tri, les liens associés, les métadonnées de recherche, les alternatives de langue et les tableaux d’aperçu générés.

Manifestes d’interface#

Les composants et les shortcodes utilisent un seul contrat de métadonnées. Il permet à chaque section canonique de rester centrée sur son public, tout en donnant aux index générés et à un futur inventaire unifié les mêmes champs à lire.

interface_kind: "component"
interface_category: "navigation"
interface_status: "implemented"
interface_implementation:
  partial:
    - layouts/partials/data-page/anchor-index.html
  css:
    - assets/css/site.css
  i18n:
    - airlineCodesAnchorIndexLabel
interface_consumers:
  - layout: layouts/partials/docs/shell.html
  - site: main
    page: /blog/ref/airline-codes
    label_key: interfaceConsumerAirlineCodes

Utilisez layout pour un gabarit source qui consomme l’interface. Utilisez site, page et label_key pour une page rendue; label_key est requis lorsque cette page se trouve sur un autre site.

interface_kind vaut component ou shortcode. Les composants portent aussi une interface_category, par exemple navigation, action, content, data, layout ou utility. interface_status vaut specified, implemented ou deprecated.

interface_preview consigne une exception à l’exemple encadré ou direct normal. Utilisez page lorsque l’habillage de la page courante rend le composant, render-hook lorsqu’un crochet de rendu Markdown produit l’exemple, ou consumer lorsqu’une autre page fournit les données ou la composition requises. Un enregistrement consumer déclare aussi interface_preview_page et pointe vers cette page avec component-relationship. Omettez les deux champs lorsque la documentation contient déjà component-preview, le vrai balisage du composant ou un shortcode d’implémentation actif.

interface_implementation est une carte de preuves. Ses clés sont les mécanismes employés par l’interface : partial, shortcode, layout, data, css, js, i18n ou configuration. Chaque valeur énumère les fichiers source pertinents; pour i18n, elle énumère les clés statiques lues directement par l’interface. Ainsi, le mécanisme reste avec sa preuve et le manifeste demeure utile autant pour les personnes que pour la validation. related_interfaces contient les chemins de documentation d’un composant ou d’un shortcode lié; omettez le champ lorsqu’il n’y a aucune relation.

Utilisez seulement les mécanismes présents dans data/interfaces.yml. Ne consignez que des fichiers et des clés statiques vérifiés; ne répétez pas la prose de la page dans les métadonnées. interface_source est un champ hérité de compatibilité pour les enregistrements qui n’ont pas encore été audités. Ne l’ajoutez pas aux enregistrements nouveaux ou mis à jour.

Utilisez immédiatement avant le titre ## Accessibilité. Il rend une liste de descriptions ### Manifeste d’interface à partir de ces champs; ne le dupliquez pas dans la prose de la page. Les champs alimentent l’index groupé des composants et deviendront la source de vérité d’un futur inventaire filtrable.

Manifestes de motifs#

Les motifs utilisent un contrat pattern_* parallèle parce qu’ils consignent des compositions plutôt qu’une seule unité d’interface. Il garde la tâche, les composants constitutifs, les besoins de contenu et de données, l’accessibilité au niveau de la composition et les preuves d’implémentation lisibles par la machine sans surcharger les métadonnées de composants.

Utilisez Bibliothèque de motifs pour la forme des champs, la recette de page, le {{< pattern-manifest >}} généré et la validation npm run lint:patterns. Utilisez Bibliothèque de motifs pour la frontière de décision.

Formes de dossiers#

Les formes de dossiers récurrentes sont stables et appuyées par Archétypes lorsqu’un fichier de départ est utile :

Utilisez un archétype physique lorsqu’un patron se répète assez souvent pour que la copie manuelle crée de la dérive. Copiez la page publiée la plus proche seulement lorsque la nouvelle page a besoin d’un contenu ou d’un comportement inhabituellement spécifique.

Tableaux avec cellules riches#

Les tableaux Markdown simples sont préférables. Utilisez du HTML en ligne dans une cellule seulement lorsque le contenu a besoin d’une structure que les tableaux Markdown ne peuvent pas exprimer proprement.

Permis pour un usage occasionnel :

<br />
<ul>
  <li>Partial Hugo ← <code>layouts/partials/data-page/anchor-index.html</code></li>
  <li>CSS ← <code>assets/css/site.css</code></li>
</ul>

Utilisez un partial ou un shortcode lorsque la même forme de tableau riche apparaît plus d’une fois. Un motif répété ne devrait pas dépendre de HTML écrit à la main dans chaque fichier Markdown. Les bons candidats sont les tableaux de profil de composant, les tableaux d’options et les listes de sources d’implémentation.