docs(v2): Add documentation for docs multi-instance support (#3978)

* Add documentation for docs multi-instance support

* Add documentation for docs multi-instance support

website/docs/api/themes/theme-configuration.md

@@ -273,10 +273,13 @@ module.exports = {
         // highlight-start
         {
           type: 'doc',
-          position: 'left',
           docId: 'introduction',
+
+          //// Optional
+          position: 'left',
           label: 'Docs',
           activeSidebarClassName: 'navbar__link--active',
+          docsPluginId: 'default',
         },
         // highlight-end
       ],
@@ -296,14 +299,15 @@ module.exports = {
       items: [
         {
           type: 'docsVersionDropdown',
-          position: 'left',
 
+          //// Optional
+          position: 'left',
           // Add additional dropdown items at the beginning/end of the dropdown.
           dropdownItemsBefore: [],
           dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
-
           // Do not add the link active class when browsing docs.
           dropdownActiveClassDisabled: true,
+          docsPluginId: 'default',
         },
       ],
     },
@@ -323,9 +327,12 @@ module.exports = {
         // highlight-start
         {
           type: 'docsVersion',
+
+          //// Optional
           position: 'left',
-          // to: "/path // by default, link to active/latest version
+          to: '/path', // by default, link to active/latest version
-          // label: "label" // by default, show active/latest version label
+          label: 'label', // by default, show active/latest version label
+          docsPluginId: 'default',
         },
         // highlight-end
       ],

website/docs/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 documentations](./versioning.md). 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/\*](/docs) section is versioned
+- The [/community/\*](/community/support) 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:
+
+```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
+
+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:
+
+```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
+
+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
+        },
+      ],
+    },
+  },
+};
+```

website/docs/using-plugins.md

@@ -78,9 +78,11 @@ module.exports = {
 
 ## Multi-instance plugins and plugin ids
 
-It is possible to use multiple times the same plugin, on the same Docusaurus website.
+All Docusaurus content plugins can support multiple plugin instances.
 
-In this case, it is required to assign a unique id to each plugin instance.
+The Docs plugin has [additional multi-instance documentation](./guides/docs/docs-multi-instance.mdx)
+
+It is required to assign a unique id to each plugin instance.
 
 By default, the plugin id is `default`.
 
@@ -105,6 +107,12 @@ module.exports = {
 };
 ```
 
+:::note
+
+At most one plugin instance can be the "default plugin instance", by omitting the `id` attribute, or using `id: 'default'`.
+
+:::
+
 ## Plugins design
 
 Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.

website/sidebars.js

@@ -27,9 +27,10 @@ module.exports = {
           Docs: [
             'guides/docs/introduction',
             'guides/docs/create-doc',
-            'guides/docs/markdown-features',
             'guides/docs/sidebar',
             'guides/docs/versioning',
+            'guides/docs/markdown-features',
+            'guides/docs/multi-instance',
           ],
         },
         'blog',