Gestion des versions

You can use the versioning CLI to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory continues to evolve.

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. Versioning is best suited for websites with high-traffic and rapid changes to documentation between 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.

Overview

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

The versions.json file is a list of version names, ordered from newest to oldest.

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

The files in the docs directory belong to the current docs version.

By default, the current docs version is labeled as Next and hosted under /docs/next/*, but it is entirely configurable to fit your project's release lifecycle.

Terminology

Notez la terminologie que nous utilisons ici.

Current version

The version placed in the ./docs folder.

Latest version / last version

The version served by default for docs navbar items. Habituellement a le chemin /docs.

Current version is defined by the file system location, while latest version is defined by the the navigation behavior. Il peut s'agir ou non de la même version ! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next and latest at /docs.)

Tutorials

Tagging a new version

1. First, make sure the current docs version (the ./docs directory) is ready to be frozen.
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 :

• Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder.
• Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as versioned_sidebars/version-[versionName]-sidebars.json.
• Append the new version number to versions.json.

Creating new 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.

Current version structure

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

Older version structure

# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json

Updating an existing version

You can update multiple docs versions at the same time because each directory in versioned_docs/ represents specific routes when published.

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

Example: When you change any file in versioned_docs/version-2.6/, it will only affect the docs for version 2.6.

Deleting an existing version

Vous pouvez également supprimer/retirer des versions.

1. Remove the version from versions.json.

Exemple :

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

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

Configuring versioning behavior

The "current" version is the version name for the ./docs folder. 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). In this case, the current version is v2, which is in the ./docs source folder, and can be browsed at example.com/docs/next. The latest version is v1, which is in the ./versioned_docs/version-1 source folder, and is browsed by most of your users at example.com/docs.
• Vous publiez la v1, et la maintiendrez pendant une certain temps avant de penser à la v2. In this case, the current version and latest version will both be point to v1, since the v2 docs doesn't even exist yet!

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.

For the 2nd use case: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (./docs + ./versioned_docs/version-1.0.0), you may consider "pretending" that the current version is a cut version by giving it a path and a label:

docusaurus.config.js

module.exports = {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

The docs in ./docs will be served at /docs/1.0.0 instead of /docs/next, and 1.0.0 will become the default version we link to in the navbar dropdown, and you will only need to maintain a single ./docs folder.

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

• disableVersioning: Explicitly disable versioning even with versions. Ainsi, le site n'inclura que la version actuelle.
• includeCurrentVersion: Include the current version (the ./docs folder) of your docs.
  • Tip: turn it off if the current version is a work-in-progress, not ready to be published.
• lastVersion: Sets which version "latest version" (the /docs route) refers to.
  • Tip: lastVersion: 'current' makes sense if your current version refers to a major version that's constantly patched and released. Le chemin de base et le libellé de la dernière version sont configurables.
• onlyIncludeVersions: Defines a subset of versions from versions.json to be deployed.
  • Tip: limit to 2 or 3 versions in dev and deploy previews to improve startup and build time.
• versions: A dictionary of version metadata. Pour chaque version, vous pouvez personnaliser les éléments suivants :
  • label: the label displayed in the versions dropdown and banner.
  • path: the route base path of this version. By default, latest version has / and current version has /next.
  • banner: one of 'none', 'unreleased', and '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: show a badge with the version name at the top of a doc of that version.
  • className: add a custom className to the <html> element of doc pages of that version.

See docs plugin configuration for more details.

Navbar items

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: a link to a doc.
• docSidebar: a link to the first item in a sidebar.
• docsVersion: a link to the main doc of the currently viewed version.
• docsVersionDropdown: a dropdown containing all the versions available.

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

1. Active version: the version that the user is currently browsing, if she is on a page provided by this doc plugin. Si elle n'est pas sur une page de doc, elle se rabat sur la...
2. Preferred version: the version that the user last viewed. S'il n'y a pas d'historique, elle se rabat sur la...
3. Latest version: the default version that we navigate to, configured by the lastVersion option.

Recommended practices

Version your documentation only when needed

For example, you are building documentation for your npm package foo and you are currently in 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 ? You probably shouldn't. 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.

Keep the number of versions small

En règle générale, essayez de garder le nombre de vos versions en dessous de 10. You will very likely to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 27.4, and only maintains several latest documentation versions with the lowest being 25.X. Limitez les 😊

archive older versions

If you deploy your site on a Jamstack provider (e.g. Netlify), the provider will save each production build as a snapshot under an immutable URL. 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.

Use absolute import within the docs

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). You can utilize the @site alias provided by Docusaurus that points to the website directory. Exemple :

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

Link docs by file paths

Refer to other docs by relative file paths with the .md extension, so that Docusaurus can rewrite them to actual URL paths during building. Les fichiers seront liés à la version correspondante.

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

Global or versioned collocated assets

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)

If your assets are global, put them in /static and use absolute paths:

![img alt](/myImage.png)

[download this file](/file.pdf)