Ir para o conteúdo principal
Version: 2.0.0-beta.4

Multi-instância da Docs

O plugin @docusaurus/plugin-content-docs pode suportar multi-instância.

note

Esse recurso só é útil para versões de documentação. É recomendável estar familiarizado com o versionamento de documentos antes de ler esta página.

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)

Nesse caso, você pode usar uma instância distinta de plugin de docs por documentação móvel SDK.

caution

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:

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.

caution

@docusaurus/preset-classic já inclui uma instância do plugin de docs para você!

Ao usar a predefinição:

docusaurus.config.js
module.exports = {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          // id: 'product', // omitted => default instance          path: 'product',          routeBasePath: 'product',          sidebarPath: require.resolve('./sidebarsProduct.js'),          // ... other options        },      },    ],  ],  plugins: [    [      '@docusaurus/plugin-content-docs',      {        id: 'community',        path: 'community',        routeBasePath: 'community',        sidebarPath: require.resolve('./sidebarsCommunity.js'),        // ... other options      },    ],  ],};

Quando não estiver usando a predefinição:

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        // id: 'product', // omitted => default instance        path: 'product',        routeBasePath: 'product',        sidebarPath: require.resolve('./sidebarsProduct.js'),        // ... other options      },    ],    [      '@docusaurus/plugin-content-docs',      {        id: 'community',        path: 'community',        routeBasePath: 'community',        sidebarPath: require.resolve('./sidebarsCommunity.js'),        // ... other options      },    ],  ],};

Não se esqueça de atribuir um atributo id exclusivo para instâncias de plugins.

note

Nós consideramos que o produto é a instância mais importante e torna-a a instância "padrão" ao não atribuir qualquer 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
tip

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#

Cada instância de plugin terá seu próprio comando cli para marcar uma nova versão. Eles serão exibidos se você executar:

npm run docusaurus -- --help

Para criar a versão da instância do plug-in do produto/documentos padrão:

npm run docusaurus docs:version 1.0.0

Para versão a instância do plugin não-padrão/comunitária:

npm run docusaurus docs:version:community 1.0.0

Itens da barra de navegação dos documentos#

Cada itens de barra de navegação do tema de documentos tem um atributo opcional docsPluginId.

Por exemplo, se você quiser ter uma lista suspensa de versão para cada SDK móvel (iOS e Android), você pode fazer:

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',          docsPluginId: 'ios',        },        {          type: 'docsVersionDropdown',          docsPluginId: 'android',        },      ],    },  },};