---
id: multi-instance
title: Docs Multi-instance
description: Use multiple docs plugin instances on a single Docusaurus site.
slug: /docs-multi-instance
---

The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.md#multi-instance-plugins-and-plugin-ids).

:::note

This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar/multiple-sidebars.md), you can do so within one plugin.

:::

## Use-cases {#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 {#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 this 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 {#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/\*](/docs) section is versioned
- The [/community/\*](/community/support) section is unversioned

## Setup {#setup}

Suppose you have 2 documentations:

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

In this case, you should use the same plugin twice in your site configuration.

:::caution

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

:::

When using the preset:

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

When not using the preset:

```js title="docusaurus.config.js"
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // highlight-start
        // id: 'product', // omitted => default instance
        // highlight-end
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: require.resolve('./sidebarsProduct.js'),
        // ... other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        // highlight-start
        id: 'community',
        // highlight-end
        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 {#versioned-paths}

Each plugin 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 {#tagging-new-versions}

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

```bash npm2yarn
npm run docusaurus -- --help
```

To version the product/default docs plugin instance:

```bash npm2yarn
npm run docusaurus docs:version 1.0.0
```

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

```bash npm2yarn
npm run docusaurus docs:version:community 1.0.0
```

## Docs navbar items {#docs-navbar-items}

Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) 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:

```js title="docusaurus.config.js"
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          // highlight-start
          docsPluginId: 'ios',
          // highlight-end
        },
        {
          type: 'docsVersionDropdown',
          // highlight-start
          docsPluginId: 'android',
          // highlight-end
        },
      ],
    },
  },
};
```