Ir para o conteúdo principal
Version: 2.0.0-beta.19

Sites versionados

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

note

Os documentos com versão normalmente devem ser migrados corretamente pela CLI de migração

Migre a sua página inicial versioned_docs

Ao contrário de v1, o cabeçalho de redução de cada documento com versão não é mais alterado usando version-${version}-${original_id} como o valor para o campo de id. 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

  • Consulte versioned_docs id como version-${version}/${id} (v2) ao invés da versão -${version}-${original_id} (v1).

Porque na v1 há uma boa chance de alguém ter criado um novo arquivo com o front matter id "version-${version}-${id}" que pode conflitar com o id de versioned_docs.

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>