Sites versionados

Leia https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning primeiro para problemas na abordagem v1.

note

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. Veja o cenário abaixo para uma melhor explicação.

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 :)

Já que vamos para snapshot e permitir que as pessoas movam (e editem) os documentos facilmente dentro da versão. The id front matter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.

Essencialmente, aqui estão as alterações necessárias em cada arquivo 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
---

Another content

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.

Portanto, usuários v1 precisam migrar seu arquivo 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

Na v2, usamos abordagem de snapshot para versão da documentação. 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. Isto não é possível na versão anterior devido à funcionalidade de fallback do 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 usa JSX para arquivos doc. Se você tiver atributos de estilo na documentação do Docusaurus 1, converta-os em objetos de estilo, por exemplo:

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

## Section

hello world

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