Gestion des versions

Vous pouvez utiliser la CLI de version pour créer une nouvelle version de documentation basée sur le contenu le plus récent dans le répertoire docs. Cet ensemble spécifique de documentation sera alors préservé et accessible même lorsque la documentation dans le répertoire docs continue d'évoluer.

attention

Pensez-y avant de commencer à versionner votre documentation - il peut devenir difficile pour les contributeurs de contribuer à son amélioration !

La plupart du temps, vous n'avez pas besoin de gestion des versions, car cela ne fait qu'augmenter le temps de construction et complexifier votre base de code. La gestion des versions est plus adaptée aux sites web à fort trafic et aux modifications rapides de la documentation entre les versions. Si votre documentation change rarement, n'ajoutez pas de gestion de version à votre documentation.

Pour mieux comprendre le fonctionnement de la gestion de version et voir s'il répond à vos besoins, vous pouvez lire ce qui suit.

Vue d'ensemble

Un site typique de doc versionné ressemble à ce qui suit :

website
├── sidebars.json        # barre latérale pour la version courante
├── docs                 # répertoire docs pour la version courante
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # fichier pour indiquer quelles versions sont disponibles
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

Le fichier versions.json est une liste de noms de version, ordonnée du plus récent au plus ancien.

Le tableau ci-dessous explique comment un fichier versionné correspond à sa version et à l'URL générée.

Chemin	Version	URL
versioned_docs/version-1.0.0/hello.md	1.0.0	/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md	1.1.0 (latest)	/docs/hello
docs/hello.md	current	/docs/next/hello

astuce

Les fichiers dans le répertoire docs appartiennent à la version docs current.

Par défaut, la version de docs current est marquée comme Next et hébergée dans /docs/next/*, mais elle est entièrement configurable pour correspondre au cycle de vie de votre projet.

Terminologie

Notez la terminologie que nous utilisons ici.

Version actuelle

La version placée dans le répertoire ./docs .

Dernière version

La version servie par défaut pour les éléments de la barre de navigation des docs. Habituellement a le chemin /docs.

La version actuelle est définie par l'emplacement du système de fichiers, alors que la dernière version est définie par le comportement de navigation. Il peut s'agir ou non de la même version ! (Et la configuration par défaut, comme indiqué dans le tableau ci-dessus, les traiterait comme différentes : la version actuelle vers /docs/next et la dernière vers /docs.)

Tutoriels

Étiquetage d'une nouvelle version

1. Tout d'abord, assurez-vous que la version actuelle de la documentation (le répertoire ./docs) est prête à être gelée.
2. Entrez un nouveau numéro de version.

npm

npm run docusaurus docs:version 1.1.0

Yarn

yarn docusaurus docs:version 1.1.0

pnpm

pnpm run docusaurus docs:version 1.1.0

Lorsqu'on tague une nouvelle version, le mécanisme de gestion des versions du document :

• Copie le contenu complet du dossier docs/ dans un nouveau dossier versioned_docs/version-[versionName]/.
• Crée un fichier de barres latérales versionnées basé sur la configuration de votre barre latérale actuelle (si elle existe) - enregistré sous versioned_sidebars/version-[versionName]-sidebars.json.
• Ajoute le nouveau numéro de version à versions.json.

Création de nouvelles docs

1. Placez le nouveau fichier dans le dossier de la version correspondante.
2. Ajoutez la référence du nouveau fichier dans le fichier de la barre latérale correspondante, selon le numéro de version.

Structure de la version actuelle

# Le fichier new.
docs/new.md

# Modifie le fichier correspondant à la barre latérale.
sidebars.js

Structure de l'ancienne version

# Le fichier new.
versioned_docs/version-1.0.0/new.md

# Modifie le fichier correspondant à la barre latérale.
versioned_sidebars/version-1.0.0-sidebars.json

astuce

Les fichiers de barres latérales versionnées sont, comme les fichiers de barres latérales standard, relatifs à la racine du contenu pour la version donnée :

{
  "sidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

ou pour une barre latérale manuelle :

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

Mise à jour d'une version existante

Vous pouvez mettre à jour plusieurs versions de docs en même temps car chaque répertoire de versioned_docs/ représente des routes spécifiques lorsqu'elles sont publiées.

1. Modifiez n'importe quel fichier.
2. Validez et soumettez les modifications.
3. Il sera publié dans la version.

Exemple: Lorsque vous changez n'importe quel fichier dansversioned_docs/version-2.6/, cela n'affectera que la documentation pour la version 2.6.

Suppression d'une version existante

Vous pouvez également supprimer/retirer des versions.

1. Retirez la version depuis le fichier versions.json.

Exemple :

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

2. Supprimez le répertoire de la documentation versionnée. Exemple : versioned_docs/version-1.8.0.
3. Supprimez le fichier versionné de la barre latérale. Exemple : versioned_sidebars/version-1.8.0-sidebars.json.

Configuration du comportement des versions

La version « actuelle » est le nom de la version de la documentation qui se trouve dans le dossier ./docs. Il y a différentes manières de gérer les versions, mais les deux pratiques courantes sont :

• Vous publiez la v1 et commencez immédiatement à travailler sur la v2 (y compris sa documentation). Dans ce cas, la version actuelle est v2, qui se trouve dans le dossier source ./docs, et peut être parcouru via example.com/docs/next. La dernière version est v1, qui est dans le dossier source ./versioned_docs/version-1, et est parcouru par la plupart de vos utilisateurs via example.com/docs.
• Vous publiez la v1, et la maintiendrez pendant une certain temps avant de penser à la v2. Dans ce cas, la version actuelle et la dernière version pointeront vers v1, car la v2 des docs n'existe pas encore !

La configuration par défaut de Docusaurus fonctionnent très bien pour le premier cas d'utilisation. Nous allons étiqueter la version actuelle comme "next" et vous pouvez même choisir de ne pas la publier.

Pour le 2nd cas : si vous publiez la v1 et ne prévoyez pas de travailler sur la v2 bientôt, au lieu de versionner la v1 et d'avoir à maintenir les fichiers dans deux dossiers (./docs + ./versioned_docs/version-1.0.0), vous pouvez envisager de « prétendre » que la version actuelle est une version découpée en lui donnant un chemin et un libellé :

docusaurus.config.js

export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

Les docs dans ./docs seront servis depuis /docs/1.0.0 au lieu de /docs/next et 1.0.0 deviendra la version par défaut vers laquelle nous avons un lien dans le menu déroulant de la barre de navigation, et vous n'aurez besoin que de maintenir un seul dossier ./docs.

Nous offrons ces options de plugin pour personnaliser le comportement des versions :

• disableVersioning : Désactive explicitement le versionnage même avec les versions. Ainsi, le site n'inclura que la version actuelle.
• includeCurrentVersion : Inclue la version actuelle (le dossier ./docs) de vos docs.
  • Astuce : désactivez-le si la version actuelle est en cours, pas prête à être publiée.
• lastVersion : Définit à quelle version la "dernière version" (la route /docs) fait référence.
  • Astuce : lastVersion: 'current' a un sens si votre version actuelle fait référence à une version majeure constamment corrigée et publiée. Le chemin de base et le libellé de la dernière version sont configurables.
• onlyIncludeVersions : Définit un sous-ensemble de versions de versions.json à déployer.
  • Astuce : limitez à 2 ou 3 versions en dev et déployez des aperçus pour améliorer le temps de démarrage et de compilation.
• versions : Un dictionnaire de métadonnées de version. Pour chaque version, vous pouvez personnaliser les éléments suivants :
  • label : le libellé affiché dans le menu déroulant des versions et la bannière.
  • path : le chemin de base de la route de cette version. Par défaut, la dernière version a / et la version actuelle a /next.
  • banner : l'une des valeurs suivantes 'none', 'unreleased' et 'unmaintained'`. Détermine ce qui est affiché en haut de chaque page de documentation. Toute version supérieure à la dernière version serait "unreleased", et toute version inférieure serait "unmaintained".
  • badge : montre un badge avec le nom de version en haut d'un doc de cette version.
  • className : ajoute un className personnalisé à l'élément <html> aux pages de doc de cette version.

Consultez la configuration du plugin des docs pour plus de détails.

Éléments de la barre de navigation

Nous offrons plusieurs éléments de la barre de navigation pour vous aider à configurer rapidement la navigation sans vous soucier des routes versionnées.

• doc : un lien vers un doc.
• docSidebar : un lien vers le premier élément d'une barre latérale.
• docsVersion : un lien vers le doc principal de la version actuellement consultée.
• docsVersionDropdown : un menu déroulant contenant toutes les versions disponibles.

Ces liens rechercheront tous une version appropriée à laquelle se rattacher, dans l'ordre suivant :

1. Version active : la version sur laquelle l'utilisateur navigue actuellement, si elle se trouve sur une page fournie par ce plugin de doc. Si elle n'est pas sur une page de doc, elle se rabat sur la...
2. Version préférée : la version que l'utilisateur a consultée pour la dernière fois. S'il n'y a pas d'historique, elle se rabat sur la...
3. Dernière version : la version par défaut vers laquelle nous naviguons, configurée par l'option lastVersion.

Pratiques recommandées

Versionnez votre documentation uniquement lorsque c'est nécessaire

Par exemple, vous créez une documentation pour votre paquet npm foo et vous êtes actuellement à la version 1.0.0. Vous publiez ensuite une version de patch pour une correction mineure, soit la version 1.0.1.

Faut-il créer une nouvelle documentation version 1.0.1 ? Vous ne devriez probablement pas. Les version 1.0.1 et 1.0.0 ne devraient pas différer selon la gestion sémantique semver, car il n'y a pas de nouvelles fonctionnalités ! Mettre en place cette nouvelle version ne fera que créer des fichiers inutilement dupliqués.

Limitez le nombre de versions

En règle générale, essayez de garder le nombre de vos versions en dessous de 10. Vous allez très probablement avoir beaucoup de documentation obsolète versionnée que personne ne lit plus. Par exemple, Jest est actuellement dans la version 27.4 et ne maintient uniquement que les dernières versions de la documentation, la plus basse étant 25.X. Limitez les 😊

archiver les anciennes versions

Si vous déployez votre site sur un fournisseur de Jamstack (par exemple Netlify), le fournisseur sauvegardera chaque version de production en tant qu'instantané sous une URL immuable. Vous pouvez inclure des versions archivées qui ne seront jamais reconstruites en tant que liens externes vers ces URL immuables. Le site de Jest et le site Web de Docusaurus utilisent tous deux ce modèle pour réduire le nombre de versions activement construites.

Utilisez l'importation absolue dans la documentation

N'utilisez pas de chemins relatifs à l'importation dans la documentation. Parce que lorsque nous créons une version, les chemins ne fonctionnent plus (le niveau d'imbrication est différent, entre autres raisons). Vous pouvez utiliser l'alias @site fourni par Docusaurus qui pointe vers le répertoire website. Exemple :

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

Liez des documents par des chemins de fichiers

Faites référence à d'autres documents par des chemins de fichiers relatifs avec l'extension .md, afin que Docusaurus puisse les réécrire en chemins d'URL réels pendant la construction. Les fichiers seront liés à la version correspondante.

Le document [@hello](hello.mdx#paginate) est génial !

Voir le [Tutoriel](../getting-started/tutorial.mdx) pour plus d'informations.

Ressources colocalisées globalement ou versionnées

Vous devez décider si les ressources comme les images et les fichiers sont par version ou partagées entre les versions.

Si vos ressources doivent être versionnés, mettez-les dans la version docs et utilisez des chemins relatifs :

![img alt](./myImage.png)

[download this file](./file.pdf)

Si vos ressources sont globales, mettez-les dans /static et utilisez des chemins absolus :

![img alt](/myImage.png)

[download this file](/file.pdf)