Multi-instância da Docs
The @docusaurus/plugin-content-docs
plugin can support multi-instance.
This feature is only useful for versioned documentation. É recomendável estar familiarizado com o versionamento de documentos antes de ler esta página. If you just want multiple sidebars, you can do so within one plugin.
Casos de uso
Às vezes você quer um site Docusaurus para hospedar 2 conjuntos distintos de documentação (ou mais).
Estas documentações podem até ter diferentes ciclos de versão/liberação.
Documentação do Mobile SDKs
Se você criar um SDK móvel multiplataforma, você pode ter 2 documentações:
- Documentação do Android SDK (
v1.0
,v1.1
) - documentação do iOS SDK (
v1.0
,v2.0
)
In this case, you can use a distinct docs plugin instance per mobile SDK documentation.
Se cada instância de documentação for muito grande, você prefere criar 2 sites do Docusaurus distintos.
Se alguém editar a documentação do iOS, é realmente útil reconstruir tudo, incluindo toda a documentação do Android que não mudou?
Documento versionado e não versionado
Às vezes, você quer que alguns documentos sejam versionados, enquanto outros documentos são mais "globais" e parece inútil versioná-los.
Usamos esse padrão no próprio site do Docusaurus:
- A seção /docs/* está versionada
- A seção /community/* não está versionada
Configuração
Suponha que você tem 2 documentações:
- Produto: algum documento versionado sobre seu produto
- Comunidade: algum documento não versionado sobre a comunidade em torno do seu produto
Neste caso, você deve usar o mesmo plugin duas vezes na configuração do seu site.
@docusaurus/preset-classic
já inclui uma instância do plugin de docs para você!
Ao usar a predefinição:
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
],
};
Quando não estiver usando a predefinição:
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
],
};
Não se esqueça de atribuir um atributo id
exclusivo para instâncias de plugins.
We consider that the product
instance is the most important one, and make it the "default" instance by not assigning any ID.
Caminhos versionados
Cada instância do plugin armazenará documentos versionados em uma pasta distinta.
A instância padrão do plugin usará esses caminhos:
website/versions.json
website/versioned_docs
website/versioned_sidebars
As outras instâncias de plugin (com um atributo id
) usarão esses caminhos:
website/[pluginId]_versions.json
website/[pluginId]_versioned_docs
website/[pluginId]_versioned_sidebars
Você pode omitir o atributo id
(o padrão é default
) para uma das instâncias do plugin da documentação.
Os caminhos da instância serão mais simples e compatíveis com uma configuração de uma única instância.
Marcando novas versões
Each plugin instance will have its own CLI command to tag a new version. Eles serão exibidos se você executar:
- npm
- Yarn
- pnpm
npm run docusaurus -- --help
yarn docusaurus --help
pnpm run docusaurus --help
Para criar a versão da instância do plug-in do produto/documentos padrão:
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.0.0
yarn docusaurus docs:version 1.0.0
pnpm run docusaurus docs:version 1.0.0
Para versão a instância do plugin não-padrão/comunitária:
- npm
- Yarn
- pnpm
npm run docusaurus docs:version:community 1.0.0
yarn docusaurus docs:version:community 1.0.0
pnpm run docusaurus docs:version:community 1.0.0
Itens da barra de navegação dos documentos
Each docs-related theme navbar items take an optional docsPluginId
attribute.
Por exemplo, se você quiser ter uma lista suspensa de versão para cada SDK móvel (iOS e Android), você pode fazer:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};