Plusieurs versions

Une ref devient une version. Pointez une source vers des tags et chacun est publié, avec un segment de version dans l’URL et une entrée dans le sélecteur.

Les refs exigent un repo explicite, même pour publier un autre ref de ce dépôt. Sans repo, une source lit le checkout local actuel et refuse refs (y compris latest) ainsi que les substitutions locales de ref par langue. origin.repo et origin.ref fournissent uniquement des liens de provenance ; ils ne sélectionnent aucun contenu. Une langue ayant son propre repo explicite peut choisir son propre ref. Pour les versions locales, utilisez version sur des sources avec des dossiers distincts ou les versions par fichier d’une section générée.

#Étapes

#La granularité d’une version

Le nom est le choix du site, pas du mécanisme, et c’est la décision essentielle ici : chaque lien vers votre documentation le portera.

Une ligne par version, sous forme de branche. C’est le choix de Laravel, Symfony et Django : 11.x, 10.x et 9.x sont des branches qui continuent d’évoluer, et un correctif ne change rien à l’URL.

sources: [
  {
    repo: 'acme/api',
    path: 'docs',
    refs: [
      { branch: '12.x', status: 'upcoming' },
      '11.x',
      { branch: '10.x', status: 'deprecated' },
      { branch: '9.x', status: 'eol' }
    ]
  }
],
sourceOptions: { defaultRef: '11.x' }

Une chaîne simple est une branche ; seul un tag doit le préciser.

Une ligne par version, depuis des tags. Lorsque la version publiée est un tag mais que l’URL ne doit pas changer à chaque correctif, label la renomme :

refs: [
  { tag: 'v2.4.1', label: 'v2' },
  { tag: 'v1.9.3', label: 'v1', status: 'deprecated' }
]

Chaque publication a sa propre version. { tag: 'v2.4.1' } sans libellé. Chacune reste citable pour toujours, et le sélecteur gagne une entrée à chaque publication : adapté à une spécification, mais pas à un manuel.

Les mêmes politiques peuvent être entretenues depuis les tags plutôt que répétées dans la configuration :

// Chaque publication qui doit rester citable.
releases: { select: 'all' }

// Ou le dernier correctif de chaque ligne mineure durable.
releases: { select: 'minor' }

// Ou une publication courante pour chaque ligne majeure.
releases: { select: 'major' }

La publication sélectionnée la plus récente est celle par défaut, sauf si une ref explicite avec default: true ou sourceOptions.defaultRef en décide autrement. Une sélection sans tag correspondant fait échouer le build ; un dépôt injoignable est signalé comme une erreur Git, pas pris pour une sélection vide.

Le même choix vaut pour une section qui nomme ses versions : version: 'v2' ou version: '2.4.1', avec exactement le même compromis. Un modèle, une décision, que le contenu provienne d’une ref ou d’un fichier.

#Quand les versions ne sont pas des refs

Une version est normalement un checkout. Deux formes courantes ne le sont pas :

La documentation dans des dossiers. docs/v1 à côté de docs/v2 dans un dépôt, sans tags. Chaque source nomme sa version :

sources: [
  { path: 'docs/v2', version: 'v2' },
  { path: 'docs/v1', version: 'v1', status: 'deprecated' }
]

Une API dans des fichiers. openapi/v1.yaml à côté de openapi/v2.yaml est la façon habituelle de conserver une API. Les versions appartiennent à la section, pas à la source :

generated: [
  {
    type: 'openapi',
    label: 'API',
    path: 'openapi/v2.yaml',
    versions: [
      { version: 'v2', path: 'openapi/v2.yaml' },
      { version: 'v1', path: 'openapi/v1.yaml', status: 'deprecated' }
    ]
  }
]

Les deux produisent exactement ce que produisent les refs : un segment d’URL, une entrée dans le sélecteur, le bandeau et le canonical. Le sélecteur reste limité à l’artefact lu : sur /api, il propose les versions de l’API ; sur une page de prose, celles de la documentation.

#Ce qu’il advient des anciennes versions

Une version non par défaut porte noindex et un canonical pointant vers la même page dans celle par défaut, et une version eol quitte entièrement le sitemap. C’est ce qui empêche un moteur de recherche de proposer v0.9.0 là où le lecteur voulait la documentation du jour — voir URL et versions.

#Liste de contrôle

• Chaque tag est écrit { tag: … }, pas en chaîne simple
• Les noms de version suivent la granularité des lignes de support du projet
• defaultRef nomme la version sur laquelle les lecteurs doivent arriver
• Une branche de la liste porte un status explicite
• Le sélecteur affiche chaque version, avec un badge sur les mortes
• La page d’une version morte est absente de /sitemap.xml
• Si les versions sont des dossiers ou des fichiers plutôt que des refs, un seul de refs, version d’une source et versions d’une section est utilisé