Sections générées

Une source publie le Markdown que contient un dépôt. Une section générée publie quelque chose qui n’est pas du Markdown du tout : une source nomme un artefact et le type qui le lit, et les pages en découlent.

{
  path: 'docs',
  generated: [
    { type: 'changelog', path: 'CHANGELOG.md', label: 'Releases' },
    { type: 'openapi', path: 'openapi.yaml', label: 'API' }
  ]
}

La couche livre deux types — changelog et openapi — et le registre est ouvert : un site peut ajouter les siens ou en remplacer un. Les champs qu’une déclaration prend sont les mêmes pour tous les types et se trouvent dans Sources.

#Les pages sont une collection ordinaire

C’est tout l’enjeu, et cela mérite d’être dit clairement : ce qu’un type produit, ce sont des fichiers Markdown, écrits dans une collection que Content construit comme n’importe quelle autre. Donc la recherche les trouve, llms.txt les liste, le sitemap les porte, le sélecteur de versions circule entre elles, et le bouton de copie remet la page à un modèle.

Rien ici n’est un second chemin de rendu. Un type qui devrait s’apprendre à la recherche, au flux ou au sitemap serait un site parallèle à l’intérieur du site — et chacune de ces coutures est un endroit où les deux moitiés divergent.

#Ce qui appartient à un type, et ce qui n’en relève pas

Un type répond à trois questions et rien de plus : comment découper son artefact en pages, et les deux politiques ci-dessous. Il ne décide pas où va son entrée dans la barre, comment s’appelle la section, ni quel artefact il lit — cela appartient à la déclaration, parce que cela appartient au site.

#Versionnage

Les deux sont opposés, et les deux ont raison. Une description d’API appartient à la version qu’elle décrit : à un lecteur sur v1 qui demande ce que signifie un champ, il ne faut pas montrer la réponse de v2. Un journal des versions est l’inverse — ce n’est pas un document par version qui mentionne d’autres versions, c’est la liste des versions, et en construire une copie par version publierait le même fichier sous trois URL, chacune privée des versions venues ensuite.

Que le même mécanisme produise les deux est la raison pour laquelle le versionnage est une politique du type et non une règle de la couche.

#Localisation

Un type per-locale lit la table locales de la déclaration — un artefact par langue, parce qu’une description OpenAPI traduite est un vrai artefact et non le même fichier réétiqueté. Une langue que la table ne nomme pas ne construit rien, et c’est délibéré : la chaîne de repli existante lui sert alors la langue par défaut et le bandeau de traduction le dit. Déclarer un artefact pour chaque langue et servir en silence le même fichier sous chacune laisserait ce bandeau muet et le lecteur dans l’ignorance.

Un type original saute la table entièrement. Un journal des versions est écrit une fois, par l’outil de release, dans la langue où le projet commite — un site localisé sert donc l’original et le dit avec le bandeau qu’il dessine déjà.

#Où elles échouent

Un artefact local manquant, illisible, ou à qui l’on passe une option que son type ne connaît pas fait échouer le build au chargement de la configuration : la configuration propre du site est une erreur que le build ne doit pas porter, et une section devenue vide en silence est une section dont personne ne remarque l’absence.

Reste soit un artefact distant, qui peut légitimement avoir vieilli d’une version à l’autre, soit une page rendue avec quelque chose en moins. Ce sont des avertissements dans le rapport de build — voir Ce que le build vérifie.