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

Versionamento

Você pode usar o script de versão para criar uma nova versão da documentação com base no conteúdo mais recente do diretório docs. Esse conjunto específico da documentação será então preservado e acessível, mesmo que a documentação do diretório docs mude em frente.

caution

Pense nisso antes de começar a versão da sua documentação - pode se tornar difícil para os colaboradores ajudarem a melhorá-la!

Na maioria das vezes, você não precisa de versão pois ela só vai aumentar o tempo de construção e apresentar a complexidade ao seu código. Versionamento é mais adequado para sites com alto tráfego e mudanças rápidas na documentação entre as versões. Se sua documentação raramente muda, não adicione versionamento a sua documentação.

Para entender melhor como funciona o versionamento e ver se ele se adequa às suas necessidades, você pode ler abaixo.

Estrutura de diretórios#

website├── sidebars.json        # sidebar for master (next) version├── docs                 # docs directory for master (next) version│   ├── foo│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar│   └── hello.md         # https://mysite.com/docs/next/hello├── versions.json        # file to indicate what versions are available├── versioned_docs│   ├── version-1.1.0│   │   ├── foo│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar│   │   └── hello.md│   └── version-1.0.0│       ├── foo│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar│       └── hello.md├── versioned_sidebars│   ├── version-1.1.0-sidebars.json│   └── version-1.0.0-sidebars.json├── docusaurus.config.js└── package.json

A tabela abaixo explica como um arquivo versionado é mapeado para sua versão e a URL gerada.

CaminhoVersãoURL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0 (latest)/docs/hello
docs/hello.mdnext/docs/next/hello

Marcando uma nova versão#

  1. Primeiro, certifique-se de que seu conteúdo no diretório docs está pronto para ser congelado como uma versão. Uma versão deve ser sempre baseada no master.
  2. Insira um novo número de versão.
npm run docusaurus docs:version 1.1.0

Ao marcar uma nova versão, o mecanismo de controle de versão do documento irá:

  • Copiar todo o conteúdo da pasta docs/ em uma nova pasta versioned_docs/version-<version>/.
  • Crie um arquivo de barras laterais com versão baseado em sua configuração atual sidebar (se existir) - salve como versioned_sidebars/version-<version>-sidebars.json.
  • Anexar o novo número de versão a versions.json.

Docs#

Criando novos documentos#

  1. Coloque o novo arquivo na pasta da versão correspondente.
  2. Incluir a referência para o novo arquivo no arquivo da barra lateral, de acordo com o número da versão.

Documentação principal

# O novo arquivo.docs/new.md
# Editar o arquivo da barra lateral correspondente.sidebar.js

Documentos mais antigos

# O novo arquivo.versioned_docs/version-1.0.0/new.md
# Edite o arquivo da barra lateral correspondente.versioned_sidebars/version-1.0.0-sidebars.json

Vinculando documentos#

  • Lembre-se de incluir a extensão .md.
  • Os arquivos serão vinculados à versão correspondente correta.
  • Os caminhos relativos também funcionam.
O [@hello](hello.md#paginate) documento é ótimo!
Veja o [Tutorial](../getting-started/tutorial.md) para mais informações.

Versões#

Cada diretório em versioned_docs/ representará uma versão de documentação.

Atualizando uma versão existente#

Você pode atualizar várias versões de documentos ao mesmo tempo porque cada diretório em versioned_docs/ representa rotas específicas quando publicado.

  1. Edite qualquer arquivo.
  2. Faça commit e push das alterações.
  3. Será publicado na versão.

Exemplo: Quando você altera qualquer arquivo no versioned_docs/version-2.6/, isso afetará apenas a documentação para a versão 2.6.

Excluindo uma versão existente#

Você também pode excluir/remover versões.

  1. Remova a versão de versions.json.

Exemplo:

[  "2.0.0",  "1.9.0",- "1.8.0"]
  1. Exclua o diretório de documentos versionados. Exemplo: versioned_docs/version-1.8.0.
  2. Exclua o arquivo de barras laterais com versão. Exemplo: versioned_sidebars/version-1.8.0-sidebars.json.

Práticas recomendadas#

Descubra o comportamento da versão "atual"#

A versão "atual" é o nome da versão da pasta ./docs.

Existem diferentes maneiras de gerenciar versionamento, mas dois padrões muito comuns são:

  • Você libera v1 e começa a trabalhar imediatamente na v2 (incluindo sua documentação)
  • Você libera v1, e vai mantê-lo por algum tempo antes de pensar na v2.

Os padrões do Docusaurus funcionam muito bem para o primeiro caso de uso.

Para o segunda caso de uso: se você liberar v1 e não planeja trabalhar na v2 a qualquer momento em breve, em vez de versionar v1 e ter que manter a documentação em 2 pastas (./docs + ./versioned_docs/version-1.0.0), você pode considerar usar a seguinte configuração:

{  "lastVersion": "current",  "versions": {    "current": {      "label": "1.0.0",      "path": "1.0.0"    }  }}

A documentação em ./docs será servida em /docs/1.0.0 em vez de /docs/next, e 1.0.0 se tornará a versão padrão a que vinculamos no menu suspenso da barra de navegação, e basta manter uma única pasta ./docs.

Veja a configuração do plugin da documentação para mais detalhes.

Versão de sua documentação apenas quando necessário#

Por exemplo, você está construindo uma documentação para o pacote npm foo e você está atualmente na versão 1.0.0. Em seguida, lançamos uma versão de patch para uma pequena correção de bug e agora ela é 1.0.1.

Você deve cortar uma nova versão da documentação 1.0.1? Provavelmente você não deveria. Os documentos 1.0.1 e 1.0.0 não devem diferir de sempre porque não há novos recursos!. Cortar uma nova versão apenas criará arquivos duplicados desnecessários.

Mantenha o número de versões pequeno#

Como regra geral, tente manter o número de suas versões abaixo de 10. É bem provável que você tenha um monte de documentação obsoleta que ninguém sequer lê mais. Por exemplo, Jest está atualmente na versão 24., e apenas mantém várias versões mais recentes da documentação com o valor mais baixo de 22.X. Mantenha isso pequeno 😊

Usar importação absoluta nos docs#

Não use caminhos relativos importação dentro de docs. Porque quando cortamos uma versão, os caminhos não funcionam (o nível de aninhamento é diferente, entre outras razões). Você pode utilizar o alias @site fornecido pelo Docusaurus, que aponta para o diretório website. Exemplo:

- import Foo from '../src/components/Foo';+ import Foo from '@site/src/components/Foo';

Assets colocados globais ou com versão#

Você deve decidir se arquivos como imagens e arquivos são por versão ou compartilhados entre versões

Se seus assets devem ser versionados, coloque-os na versão da documentação e use caminhos relativos:

![img alt](./myImage.png)
[baixe este arquivo](./file.pdf)

Se seus assets forem globais, coloque-os em /static e use caminhos absolutos:

![img alt](/myImage.png)
[baixe este arquivo](/file.pdf)