diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md index 70f6d89996..fdb5615655 100644 --- a/website/docs/api/themes/theme-configuration.md +++ b/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 - // label: "label" // by default, show active/latest version label + to: '/path', // by default, link to active/latest version + label: 'label', // by default, show active/latest version label + docsPluginId: 'default', }, // highlight-end ], diff --git a/website/docs/guides/docs/docs-multi-instance.mdx b/website/docs/guides/docs/docs-multi-instance.mdx new file mode 100644 index 0000000000..e1ed309706 --- /dev/null +++ b/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/_versions.json` +- `website/_versioned_docs` +- `website/_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 + }, + ], + }, + }, +}; +``` diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index b9bbccff0c..7d040fe3db 100644 --- a/website/docs/using-plugins.md +++ b/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. diff --git a/website/sidebars.js b/website/sidebars.js index 70644fa1ae..cb912a6bd7 100644 --- a/website/sidebars.js +++ b/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',