Versionamento
You can use the versioning CLI to create a new documentation version based on the latest content in the docs
directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs
directory continues to evolve.
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.
Visão Geral
A typical versioned doc site looks like below:
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
The versions.json
file is a list of version names, ordered from newest to oldest.
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 |
Os arquivos no diretório docs
pertencem à versão current
do docs.
By default, the current
docs version is labeled as Next
and hosted under /docs/next/*
, but it is entirely configurable to fit your project's release lifecycle.
Terminology
Note the terminology we use here.
- Current version
- The version placed in the
./docs
folder. - Latest version / last version
- The version served by default for docs navbar items. Usually has path
/docs
.
Current version is defined by the file system location, while latest version is defined by the the navigation behavior. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next
and latest at /docs
.)
Tutorials
Marcando uma nova versão
- First, make sure the current docs version (the
./docs
directory) is ready to be frozen. - Insira um novo número de versão.
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.1.0
yarn docusaurus docs:version 1.1.0
pnpm run docusaurus docs:version 1.1.0
Ao marcar uma nova versão, o mecanismo de controle de versão do documento irá:
- Copy the full
docs/
folder contents into a newversioned_docs/version-[versionName]/
folder. - Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as
versioned_sidebars/version-[versionName]-sidebars.json
. - Anexar o novo número de versão a
versions.json
.
Criando novos documentos
- Coloque o novo arquivo na pasta da versão correspondente.
- Include the reference to the new file in the corresponding sidebar file according to the version number.
- Current version structure
- Older version structure
# O novo arquivo.
docs/new.md
# Editar o arquivo da barra lateral correspondente.
sidebars.js
# 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
Versioned sidebar files are, like standard sidebar files, relative to the content root for the given version — so for the example above, your versioned sidebar file may look like:
{
"sidebar": [
{
"type": "autogenerated",
"dirName": "."
}
]
}
or for a manual sidebar:
{
"sidebar": [
{
"type": "doc",
"id": "new",
"label": "New"
}
]
}
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.
- Edite qualquer arquivo.
- Faça commit e push das alterações.
- 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.
- Remova a versão de
versions.json
.
Exemplo:
[
"2.0.0",
"1.9.0",
- "1.8.0"
]
- Exclua o diretório de documentos versionados. Exemplo:
versioned_docs/version-1.8.0
. - Exclua o arquivo de barras laterais com versão. Exemplo:
versioned_sidebars/version-1.8.0-sidebars.json
.
Configuring versioning behavior
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:
- You release v1, and start immediately working on v2 (including its docs). In this case, the current version is v2, which is in the
./docs
source folder, and can be browsed atexample.com/docs/next
. The latest version is v1, which is in the./versioned_docs/version-1
source folder, and is browsed by most of your users atexample.com/docs
. - Você libera v1, e vai mantê-lo por algum tempo antes de pensar na v2. In this case, the current version and latest version will both be point to v1, since the v2 docs doesn't even exist yet!
Docusaurus defaults work great for the first use case. We will label the current version as "next" and you can even choose not to publish it.
For the 2nd use case: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (./docs
+ ./versioned_docs/version-1.0.0
), you may consider "pretending" that the current version is a cut version by giving it a path and a label:
export default {
presets: [
'@docusaurus/preset-classic',
docs: {
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
.
We offer these plugin options to customize versioning behavior:
disableVersioning
: Explicitly disable versioning even with versions. This will make the site only include the current version.includeCurrentVersion
: Include the current version (the./docs
folder) of your docs.- Tip: turn it off if the current version is a work-in-progress, not ready to be published.
lastVersion
: Sets which version "latest version" (the/docs
route) refers to.- Tip:
lastVersion: 'current'
makes sense if your current version refers to a major version that's constantly patched and released. The actual route base path and label of the latest version are configurable.
- Tip:
onlyIncludeVersions
: Defines a subset of versions fromversions.json
to be deployed.- Tip: limit to 2 or 3 versions in dev and deploy previews to improve startup and build time.
versions
: A dictionary of version metadata. For each version, you can customize the following:label
: the label displayed in the versions dropdown and banner.path
: the route base path of this version. By default, latest version has/
and current version has/next
.banner
: one of'none'
,'unreleased'
, and'unmaintained'
. Determines what's displayed at the top of every doc page. Any version above the latest version would be "unreleased", and any version below would be "unmaintained".badge
: show a badge with the version name at the top of a doc of that version.className
: add a customclassName
to the<html>
element of doc pages of that version.
See docs plugin configuration for more details.
Itens da barra de navegação
We offer several navbar items to help you quickly set up navigation without worrying about versioned routes.
doc
: a link to a doc.docSidebar
: a link to the first item in a sidebar.docsVersion
: a link to the main doc of the currently viewed version.docsVersionDropdown
: a dropdown containing all the versions available.
These links would all look for an appropriate version to link to, in the following order:
- Active version: the version that the user is currently browsing, if she is on a page provided by this doc plugin. If she's not on a doc page, fall back to...
- Preferred version: the version that the user last viewed. If there's no history, fall back to...
- Latest version: the default version that we navigate to, configured by the
lastVersion
option.
Práticas recomendadas
Versão de sua documentação apenas quando necessário
For example, you are building documentation for your npm package foo
and you are currently in version 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. You will very likely to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 27.4
, and only maintains several latest documentation versions with the lowest being 25.X
. Mantenha isso pequeno 😊
If you deploy your site on a Jamstack provider (e.g. Netlify), the provider will save each production build as a snapshot under an immutable URL. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docusaurus website both use such pattern to keep the number of actively built versions low.
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). You can utilize the @site
alias provided by Docusaurus that points to the website
directory. Exemplo:
- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';
Link docs by file paths
Refer to other docs by relative file paths with the .md
extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.
The [@hello](hello.mdx#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.mdx) for more info.
Global or versioned collocated assets
You should decide if assets like images and files are per-version or shared between versions.
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)