Sites versionnés

Lisez d'abord https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning pour connaître les problèmes de l'approche de la v1.

remarque

The versioned docs should normally be migrated correctly by the migration CLI

Migrate your versioned_docs front matter

Unlike v1, The Markdown header for each versioned doc is no longer altered by using version-${version}-${original_id} as the value for the actual ID field. Voir le scénario ci-dessous pour une meilleure explication.

For example, if you have a docs/hello.md.

---
id: hello
title: Hello, World !
---

Hi, Endilie here :)

When you cut a new version 1.0.0, in Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md looks like this:

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---

Hi, Endilie here :)

In comparison, Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md looks like this (exactly same as original)

---
id: hello
title: Hello, World !
---

Hi, Endilie here :)

Puisque nous optons pour l'instantanéité et permettons aux gens de déplacer (et de modifier) les documents facilement dans une version. The id front matter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.

Essentiellement, voici les changements nécessaires dans chaque fichier versioned_docs :

---
- id: version-1.0.0-hello
+ id: hello
title: Hello, World !
- original_id: hello
---
Hi, Endilie here :)

Migrate your versioned_sidebars

• Refer to versioned_docs ID as version-${version}/${id} (v2) instead of version-${version}-${original_id} (v1).

Because in v1 there is a good chance someone created a new file with front matter ID "version-${version}-${id}" that can conflict with versioned_docs ID.

For example, Docusaurus 1 can't differentiate docs/xxx.md

---
id: version-1.0.0-hello
---

Un autre contenu

vs website/versioned_docs/version-1.0.0/hello.md

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---

Hi, Endilie here :)

Since we don't allow / in v1 & v2 for front matter, conflicts are less likely to occur.

Les utilisateurs de la v1 doivent donc migrer leur fichier versioned_sidebars

Example versioned_sidebars/version-1.0.0-sidebars.json:

versioned_sidebars/version-1.0.0-sidebars.json

{
+ "version-1.0.0/docs": {
- "version-1.0.0-docs": {
    "Test": [
+    "version-1.0.0/foo/bar",
-    "version-1.0.0-foo/bar",
    ],
    "Guides": [
+    "version-1.0.0/hello",
-    "version-1.0.0-hello"
    ]
  }
}

Populate your versioned_sidebars and versioned_docs

Dans la v2, nous utilisons l'approche instantanée pour la gestion de la version de la documentation. Every versioned docs does not depends on other version. It is possible to have foo.md in version-1.0.0 but it doesn't exist in version-1.2.0. Ceci n'est pas possible dans la version précédente en raison de la fonctionnalité de repli de Docusaurus v1 (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality).

For example, if your versions.json looks like this in v1

versions.json

["1.1.0", "1.0.0"]

Docusaurus v1 creates versioned docs if and only if the doc content is different. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is hello.md.

website
├── versioned_docs
│   ├── version-1.1.0
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md
│       └── hello.md
├── versioned_sidebars
│   └── version-1.0.0-sidebars.json

In v2, you have to populate the missing versioned_docs and versioned_sidebars (with the right front matter and ID reference too).

website
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json

Convert style attributes to style objects in MDX

Docusaurus 2 utilise JSX pour les fichiers doc. Si vous avez des attributs de style dans vos docs Docusaurus 1, convertissez-les en objets de style, comme ceci :

---
id: demo
title: Demo
---

## Section

hello world

- pre style="background: black">zzz</pre>
+ pre style={{background: 'black'}}>zzz</pre>