Aller au contenu principal
Version: 2.0.0-beta.4

Gestion des versions

Vous pouvez utiliser le script 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 évolue.

caution

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.

Structures des dossiers#

website├── sidebars.json        # barre latérale pour la version du master (prochaine)├── docs                 # répertoire docs pour la version du master (prochaine)│   ├── 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 tableau ci-dessous explique comment un fichier versionné correspond à sa version et à l'URL générée.

CheminVersionURL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0 (dernière)/docs/hello
docs/hello.mdprochaine/docs/next/hello

Taguer une nouvelle version#

  1. Tout d'abord, assurez-vous que votre contenu dans le répertoire docs est prêt à être figé en tant que version. Une version doit toujours être basée depuis le master.
  2. Entrez un nouveau numéro de version.
npm run docusaurus docs:version 1.1.0

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

  • Copiera le contenu complet du dossier docs/ dans un nouveau dossier versioned_docs/version-<version>/.
  • Créera un fichier de barres latérales versionnées basé sur votre configuration actuelle sidebar (si elle existe) - enregistré sous le nom versioned_sidebars/version-<version>-sidebars.json.
  • Ajoutera le numéro de la nouvelle version à versions.json.

Docs#

Création de nouvelles docs#

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

Docs master

# Le nouveau fichier.docs/new.md
# Modifier le fichier de la barre latérale correspondante.sidebar.js

Anciens Docs

# Le nouveau fichier.versioned_docs/version-1.0.0/new.md
# Modifier le fichier de la barre latérale correspondante.versioned_sidebars/version-1.0.0-sidebars.json

Liaison des docs#

  • N'oubliez pas d'inclure l'extension .md.
  • Les fichiers seront liés à la version correspondante.
  • Les chemins relatifs fonctionnent aussi.
Le document [@hello](hello.md#paginate) est génial !
Voir le [Tutoriel](../getting-started/tutorial.md) pour plus d'informations.

Versions#

Chaque répertoire dans versioned_docs/ représentera une version de la documentation.

Mise à jour d'une version existante#

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

  1. Modifier n'importe quel fichier.
  2. Commiter et pousser les changements.
  3. Il sera publié dans la version.

Exemple: Lorsque vous changez n'importe quel fichier dans versioned_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"]
  1. Supprimez le répertoire de la documentation versionnée. Exemple : versioned_docs/version-1.8.0.
  2. Supprimer le fichier des barres latérales versionnées. Exemple : versioned_sidebars/version-1.8.0-sidebars.json.

Pratiques recommandées#

Déterminer le comportement de la version « current »#

La version « current » 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)
  • Vous publiez la v1, et la maintiendrez pendant une certain temps avant de penser à la v2.

La configuration par défaut de Docusaurus fonctionnent très bien pour le premier cas d'utilisation.

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 d'utiliser la configuration suivante à la place :

{  "lastVersion": "current",  "versions": {    "current": {      "label": "1.0.0",      "path": "1.0.0"    }  }}

Les docs dans ./docs seront servis depuis /docs/1. . 0 au lieu de /docs/next et 1.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.

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

Versionner 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. Il est très probable que vous aurez beaucoup de documentation obsolète versionnée que personne ne lit plus. Par exemple, Jest est actuellement dans la version 24.9 et ne maintient uniquement les dernières versions de la documentation, la plus basse étant 22.X. Limitez les 😊

Utiliser 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';

Ressources localisé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)