Déclarer la section

Un historique des versions est une section générée : une source nomme le fichier et le type qui le lit, et les pages en découlent.

export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'changelog',
            path: 'CHANGELOG.md',
            label: 'Releases'
          }
        ]
      }
    ]
  }
})

Les champs qu’une déclaration prend sont les mêmes pour tous les types et se trouvent dans Sources. changelog nomme une option propre — granularity — et répond aux deux politiques ci-dessous.

#Versionnage

Par version. Chaque version publiée de la documentation a son propre journal des versions, lu depuis le CHANGELOG.md de cette version et servi à l’intérieur de celle-ci — /releases pour la version par défaut, /v2.x/releases à côté de /v2.x/guides. Il fonctionne exactement comme la documentation et la référence d’API à côté.

Chaque copie affiche le fichier entier livré par cette version, versions antérieures comprises : le journal d’une version plus ancienne s’arrête là où cette version s’est arrêtée. Le sélecteur de versions garde le lecteur dans le journal : sur la page d’une version, il ouvre la même version dans l’autre, et là où cette autre ne l’a jamais eue, il ouvre son aperçu du journal plutôt qu’une page absente.

Le fichier est obligatoire dans chaque version. Une version publiée sans CHANGELOG.md fait échouer le build, pour une source téléchargée comme pour le dépôt construit — omettre la version ou y montrer l’historique d’une autre publierait dans les deux cas quelque chose que cette version n’a jamais livré.

#Localisation

L’original, dans toutes les langues. Une collection, construite depuis la langue par défaut.

Un journal des versions est écrit une fois, par l’outil de release, dans la langue où le projet commite. Rien n’y est propre à une langue : un site localisé sert donc l’original et le dit avec le bandeau de traduction qu’il dessine déjà pour une page non traduite. La table locales de la déclaration n’est lue que par les types per-locale et ne fait rien ici.

#Où va l’entrée

navigation: 'sections' est la valeur par défaut et place l’entrée dans la rangée des sections — les parties de premier niveau de la documentation.

Un journal des versions n’en est souvent pas une : c’est une chose que le projet a à côté de sa documentation, non une partie de celle-ci. navigation: 'navigation' déplace l’entrée dans la première rangée, étroite, et false ne la place nulle part et laisse le site la lier.

{
  type: 'changelog',
  path: 'CHANGELOG.md',
  label: 'Releases',
  navigation: 'navigation'
}

#Le flux

duxt.feed.path nomme la section depuis laquelle /rss.xml est construit, et un historique des versions est ce pour quoi il a été écrit : chaque page de version porte la date propre de cette version, et une version est une chose qui s’est produite — ce qu’une page de référence modifiée n’est pas.

feed: { path: '/releases', title: 'mon projet — versions' }

Éteint tant que la clé n’est pas posée. Seule la version par défaut de chaque source contribue, un site versionné ne répète donc pas chaque entrée une fois par version, même si chaque version publie son propre journal des versions. Voir Configuration et /rss.xml.

#Quand le fichier ne peut pas être lu

Un fichier local absent fait échouer le build au chargement de la configuration, comme pour tout type. Ce que le fichier ne dit pas tout à fait — un titre qui ressemble à une version mais ne se lit pas comme telle — est en revanche un avertissement dans le rapport de build ; voir Ce qui est lu et Ce que le build vérifie.