Aller au contenu
duxt

Plusieurs versions

Servir la même documentation sur plusieurs refs, avec un sélecteur et un bandeau.

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.

Étapes

  1. Listez les refs. Une chaîne simple est une branche. Un tag doit le dire — git garde les deux dans des espaces de noms séparés, et demander un tag sous refs/heads fait échouer la compilation.
    sources: [
  {
    repo: 'acme/api',
    path: 'docs',
    refs: [
      { branch: 'main', status: 'upcoming' },
      { tag: 'v2.0.0' },
      { tag: 'v1.4.0' },
      { tag: 'v0.9.0', status: 'eol' }
    ]
  }
],
sourceOptions: { defaultRef: 'v2.0.0' }
  2. Nommez la version par défaut. defaultRef est la ref servie sans préfixe de version et celle vers laquelle les moteurs de recherche sont dirigés. Non définie, c’est la première de la liste — ce qui est rarement souhaitable quand la liste commence par une branche.
  3. Indiquez le cycle de vie là où il ne peut pas être déduit. Semver ordonne les tags : « plus ancienne que la version par défaut » n’a besoin d’aucune aide. Il ne peut pas situer une branche face à un tag : main est upcoming, et sans le dire on demande à son lecteur de passer à une version plus ancienne que celle qu’il lit.
  4. Utilisez latest si vous ne voulez pas modifier cette liste à chaque publication. Il se résout à la compilation vers le tag semver le plus récent de ce dépôt.
    refs: [{ branch: 'main', status: 'upcoming' }, 'latest']
  5. Signalez l’exigence de version d’une page dans le texte, là où un lecteur qui regarde une version ne voit pas les autres :
    ### Nouvelles tentatives :since{version="v2.0.0"}

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
  • 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
Cette page vous a-t-elle été utile ?