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

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 the current docs version
├── docs # docs directory for the current docs 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.mdcurrent/docs/next/hello
tip

Os arquivos no diretório docs pertencem à versão current do docs.

Por padrão, a versão current do docs é rotulada como Next e hospedada em /docs/next/*, mas é totalmente configurável para caber no ciclo de vida da liberação do seu projeto.

Marcando uma nova versão

  1. Primeiro, verifique se a versão atual da documentação (o diretório docs da documentação) está pronta para ser congelada.
  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.

Current version docs

# O novo arquivo.
docs/new.md

# Editar o arquivo da barra lateral correspondente.
sidebar.js

Documentos da versão mais antiga

# 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.

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)