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

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. For example, Jest is currently in version 24.9, and only maintains several latest documentation versions with the lowest being 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)