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.
You can edit this file, later on, to customize how you display the versions.
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.
Because of the way this fallback works, pages that you delete are not really deleted from the website unless you tell Docusaurus to skip fallback after a certain version. To do this, use the deletedDocs option in siteConfig.js.
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.