chore: prepare v2.0.0-beta.17 release (#6829)

website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-multi-instance.mdx

@@ -0,0 +1,212 @@
+---
+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
+        },
+      ],
+    },
+  },
+};
+```