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: hellotitle: 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-hellotitle: 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: hellotitle: 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. O id frontmatter não está mais alterado e continuará o mesmo. 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: hellotitle: Hello, World !- original_id: hello---Hi, Endilie here :)Migre suas versioned_sidebars#
- Consulte
versioned_docsid comoversion-${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 contentvs website/versioned_docs/version-1.0.0/hello.md
---id: version-1.0.0-hellotitle: Hello, World !original_id: hello---
Hi, Endilie here :)Como não permitimos / na v1 & v2 para frontmatter, é menor a probabilidade de ocorrerem conflitos.
Portanto, usuários v1 precisam migrar seu arquivo versioned_sidebars
Exemplo 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
["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.jsonNa v2, você tem que preencher os versioned_docs e versioned_sidebars (com a frontmatter da direita e também a referenciar o id).
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.jsonConverter 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: demotitle: Demo---
## Section
hello world
- pre style="background: black">zzz</pre>+ pre style={{background: 'black'}}>zzz</pre>