Docs Multi-instance

The @docusaurus/plugin-content-docs plugin can support multi-instance.

note

This feature is only useful for versioned documentations. It is recommended to be familiar with docs versioning before reading this page.

Use-cases#

Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).

These documentations may even have different versioning/release lifecycles.

Mobile SDKs documentation#

If you build a cross-platform mobile SDK, you may have 2 documentations:

Android SDK documentation (v1.0, v1.1)
iOS SDK documentation (v1.0, v2.0)

In such case, you can use a distinct docs plugin instance per mobile SDK documentation.

caution

If each documentation instance is very large, you should rather create 2 distinct Docusaurus sites.

If someone edits the iOS documentation, is it really useful to rebuild everything, including the whole Android documentation that did not change?

Versioned and unversioned doc#

Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.

We use this pattern on the Docusaurus website itself:

The /docs/* section is versioned
The /community/* section is unversioned

Setup#

Let's consider we 2 documentations:

Product: some versioned doc about your product
Community: some unversioned doc about the community around your product

You have to use twice the same plugin in your site configuration.

caution

@docusaurus/preset-classic already includes a docs plugin instance for you!

When using the preset:

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
      },
    ],
  ],
};

When not using the preset:

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
      },
    ],
  ],
};

Don't forget to assign a unique id attribute to plugin instances.

note

We consider that the product instance is the most important one, and make it the "default" instance by not assigning any id.

Versioned paths#

Each instance will store versioned docs in a distinct folder.

The default plugin instance will use these paths:

website/versions.json
website/versioned_docs
website/versioned_sidebars

The other plugin instances (with an id attribute) will use these paths:

website/<pluginId>_versions.json
website/<pluginId>_versioned_docs
website/<pluginId>_versioned_sidebars

tip

You can omit the id attribute (defaults to default) for one of the docs plugin instances.

The instance paths will be simpler, and retro-compatible with a single-instance setup.

Tagging new versions#

Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:

npm
Yarn

npm run docusaurus --help

To version the product/default docs plugin instance:

npm
Yarn

npm run docusaurus docs:version 1.0.0

To version the non-default/community docs plugin instance:

npm
Yarn

npm run docusaurus docs:version:community 1.0.0

Docs navbar items#

Each docs-related theme navbar items take an optional docsPluginId attribute.

For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:

docusaurus.config.js

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