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

Migre a sua página inicial versioned_docs

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.

Por exemplo, se você tem uma docs/hello.md.

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

Hi, Endilie here :)

Quando você escolher uma nova versão 1.0.0, no Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md se parece com isso:

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

Hi, Endilie here :)

Comparando, o Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md se parece com isso (exatamente como 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. Internamente, é definido como 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 :)

Migre suas 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.

Por exemplo, Docusaurus 1 não pode diferenciar 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

Exemplo 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"
    ]
  }
}

Carregue as suas versioned_sidebars e versioned_docs

Na v2, usamos abordagem de snapshot para versão da documentação. Todos os documentos versionados não dependem de outra versão. É possível ter foo.md na version-1.0.0 mas que não existe na 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).

Por exemplo, se o seu versions.json se parecer com isso na v1

versions.json

["1.1.0", "1.0.0"]

O Docusaurus v1 cria a documentação de versão se o conteúdo do documento for diferente. Sua estrutura de documentação pode parecer assim se o único documento mudou de v1.0.0 para v1.1.0 é 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

Converter atributos de estilo para objetos de estilo no 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>