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' },
    { type: 'bruno', path: 'bruno', label: 'Requests' }
  ]
}

La couche livre trois types générés — changelog, openapi et bruno — et le registre est ouvert : un site peut ajouter les siens ou en remplacer un. Les champs se trouvent dans Sources.

tfplugindocs est voisin, mais n’est volontairement pas un quatrième type généré : c’est un dialecte de source pour un arbre Markdown déjà présent. Les types générés transforment un autre artefact en pages Markdown ; un dialecte apprend à duxt la structure du Markdown existant.

#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

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 par version pour la même raison — chaque version a livré son propre CHANGELOG.md, et qui change de version reste dans le journal au lieu d’être renvoyé vers un aperçu. global reste pour un type dont l’artefact est réellement un seul historique à une URL neutre vis-à-vis des versions.

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.