Versionamento

O versionamento é um ótimo recurso para manter o histórico das suas documentações, porém, na maioria das vezes você não precisa de versionamento, pois com o tempo, isso gera aumento no tempo de construção do site (build), além de gerar complexidade no código e duplicação de páginas.

cuidado

Pense nisso antes de iniciar o versionamento de sua documentação. Pois é possível utilizar o Azure git para controlar o histórico de alterações.

Vamos entender melhor como funciona o versionamento e ver se ele se adéqua às suas necessidades.

Visão geral

Uma documentação tipicamente versionada se parece com algo assim:

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

observação

O arquivo versions.json é uma lista com os nomes das versões ordenadas da mais nova para a mais velha.

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

Caminho	Versão	URL
versioned_docs/version-1.0.0/hello.md	1.0.0	/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md	1.1.0 (latest)	/docs/hello
docs/hello.md	current	/docs/next/hello

observação

Os arquivos na pasta docs pertencem ao versão current, apelidada de next.

Criar uma nova versão

Antes de iniciar

• Primeiro certifique-se de que a versão na pasta docs está pronta para ser duplicada.

1. Abra o terminal ctrl|cmd + '
2. Digite o comando alterando o número da versão

npm run docusaurus docs:version 1.1.0

Ao criar uma nova versão, serão criadas:

• Uma cópia completa do conteúdo da pasta docs em uma nova pasta chamada versioned_docs/version-[versionName]/.
• Um novo arquivo com o versionamento da sidebar chamado versioned_sidebars/version-[versionName]-sidebars.json.
• Um novo arquivo (se não houver versões anteriores) chamado versions.json.

Deletar uma versão

Você poderá excluir uma versão do portal. Para isso:

1. Abra o arquivo versions.json
2. Escolha na lista a versão que deseja remover
3. Neste exemplo, removemos a versão "1.8.0"

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

4. Exclua a pasta com as documentações da versão removida da lista. Por exemplo: versioned_docs/version-1.8.0.
5. Exclua o arquivo de menu lateral sidebar. Por exemplo: versioned_sidebars/version-1.8.0-sidebars.json.