Versioning
Você pode usar o script version para criar uma nova versão da documentação baseada no conteúdo mais recente do diretório docs. Esse conjunto específico da documentação será então preservado e continuará acessível mesmo se forem feitas novas alterações na documentação dentro do diretório docs.
Como criar novas versões
Execute o seguinte script para gerar uma página de versões inicial listando todas as versões do site:
yarn examples versions
Isso cria o arquivo pages/en/versions.js.
Você pode editar esse arquivo mais tarde para personalizar o modo como as versões são mostradas.
Adicione o seguinte script ao seu arquivo package.json, se já não existir:
...
"scripts": {
"version": "docusaurus-version"
},
...
Execute o script passando como argumento o número da versão que você deseja criar. Por exemplo:
yarn run version 1.0.0
Isso preservará todos os documentos atualmente no diretório docs e os disponibilizará como a documentação para a versão 1.0.0.
Se, por exemplo, você executou o script de versão com 1.0.0 como o número de versão, a versão 1.0.0 é considerada como a versão mais recente do seu projeto. O site irá exibir o número de versão ao lado do título no cabeçalho. Este número de versão será um link que leva para a página de versões que você criou anteriormente.
Documentos no diretório docs serão considerados como parte da versão next e eles podem ser acessados, por exemplo, através do URL docs/next/doc1.html. Os documentos da versão mais recente usam o URL docs/doc1.html.
Executar o script novamente, dessa vez com yarn run version 2.0.0, criará a versão 2.0.0, tornando a versão 2.0.0 a mais recente na documentação. Agora, os documentos da versão 1.0.0 usarão o URL docs/1.0.0/doc1.html, enquanto que a 2.0.0 usará docs/doc1.html.
A tabela abaixo resume bem o esquema de versionamento do Docusaurus:
| Versão | Tag | URL |
|---|---|---|
| 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
| 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
| 2.0.0 | current | docs/doc1.html |
branch master | next | docs/next/doc1.html |
Padrões de versionamento
Você pode criar números de versão no formato que bem entender, e novas versões podem ser criadas usando qualquer número de versão desde que não seja o mesmo de uma versão já criada anteriormente. A ordenação das versões é determinada pela ordem em que elas foram criadas, independentemente de como são numeradas.
Armazenando arquivos para cada versão
Os documentos versionados são colocados em website/versioned_docs/version-${versão}, onde ${versão} é o numero de versão que você informou no script version.
O cabeçalho Markdown de cada documento versionado é modificado, renomeando o campo id para original_id e usando "version-${versão}-${original_id}" como o novo valor do campo id.
Barras laterais versionadas são copiadas para website/versioned_sidebars e nomeadas como version-${versão}-sidebars.json.
Um arquivo website/versions.json é criado na primeira vez que você criar uma versão, e é usado pelo Docusaurus para detectar quais versões existem. A cada vez que uma nova versão for criada, ela é adicionada ao arquivo versions.json.
Se desejar mudar a documentação para uma versão anterior, você pode acessar os arquivos dessa respectiva versão.
Funcionalidade de fallback
Apenas os arquivos do diretórios docs e arquivos da barra lateral que apresentarem diferenças em relação aos da versão mais recente serão copiados a cada vez que uma nova versão for criada. Se um arquivo não sofrer nenhuma alteração entre versões, o Docusaurus irá usar o mesmo arquivo da versão mais recente que tiver ele.
Por exemplo, um documento com o id original doc1 existe na versão mais recente, a 1.0.0, e tem o mesmíssimo conteúdo do documento com o id doc1 no diretório docs. No momento em que uma nova versão 2.0.0 for criada, o arquivo do doc1 não será copiado para versioned_docs/version-2.0.0/. Apesar da página no URL docs/2.0.0/doc1.html existir, ela vai simplesmente usar o conteúdo do arquivo presente na versão 1.0.0.
Renomeando as versões existentes
Para renomear um número de versão existente, primeiro certifique-se que o script a seguir esteja no seu arquivo package.json:
...
"scripts": {
"rename-version": "docusaurus-rename-version"
},
...
Depois, execute esse script passando dois argumentos: primeiro o nome atual da versão e, em seguida, o novo nome da versão. Por exemplo:
yarn run rename-version 1.0.0 1.0.1
Versionamento e traduções
Se você deseja usar as funcionalidades de versionamento e traduções, o arquivo crowdin.yaml precisa ser configurado para fazer o upload e download dos documentos versionados a partir do Crowdin para que sejam traduzidos. Arquivos versionados e traduzidos irão para o diretório translated_docs/${idioma}/version-${versão}/. Para mais informações, confira o guia de traduções.