Aller au contenu principal
Version: 2.0.0-beta.1 🚧

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.

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.

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 (latest)/docs/hello
docs/hello.mdnext/docs/next/hello

Taguer une nouvelle version#

  1. Tout d'abord, assurez-vous que votre contenu dans le dossier docs est prêt à être figer comme une version. Une version devrait toujours être basée sur la principale.
  2. Entrez un nouveau numéro de version.
npm run docusaurus docs:version 1.1.0

Lors de l'ajout d'une nouvelle version, le mécanisme de versionnage du document sera :

  • Copie du contenu complet du dossier docs/ dans une 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.
  • Ajout du numéro de la nouvelle version dans versions.json.

Docs#

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 celui qui gère la bare latérale correspondante, selon le numéro de version.

Documentations principales

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

Documentations plus anciennes

# 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'include l'extension .md.
  • Les fichiers seront liés à la version correspondante.
  • Les chemins relatifs fonctionnent aussi.
Le document [@bonjour](hello.md#paginate) est génial !
Voir le [Tutoriel](../getting-started/tutorial.md) pour plus d'informations.

Versions#

Chaque dossier 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. 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 dans versioned_docs/version-2.6/, ça n'affectera que la documentation de 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. Supprimez le fichier versionné de la barre latérale. 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 le versionnage, 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 fonctionne bien pour le premier cas.

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.

Devriez-vous générer une nouvelle version de la documentation 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. Gardez-le petit 😊

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)
[télécharger ce fichier](./file.pdf)

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

![img alt](/myImage.png)
[télécharger ce fichier](/file.pdf)