Skip to main content
Version: 3.5.1

文档多实例

¥Docs Multi-instance

@docusaurus/plugin-content-docs 插件可以支持 multi-instance。

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

注意

该功能仅对 版本化文档 有用。建议在阅读本页之前熟悉文档版本控制。如果你只想要 多个侧边栏，你可以在一个插件中完成此操作。

¥This feature is only useful for versioned documentation. It is recommended to be familiar with docs versioning before reading this page. If you just want multiple sidebars, you can do so within one plugin.

用例​

¥Use-cases

有时你希望 Docusaurus 站点托管 2 组不同的文档（或更多）。

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

这些文档甚至可能具有不同的版本控制/发布生命周期。

¥These documentations may even have different versioning/release lifecycles.

移动 SDK 文档​

¥Mobile SDKs documentation

如果你构建一个跨平台的移动 SDK，你可能有 2 个文档：

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

  • Android SDK 文档（v1.0、v1.1）

    ¥Android SDK documentation (v1.0, v1.1)

  • iOS SDK 文档（v1.0、v2.0）

    ¥iOS SDK documentation (v1.0, v2.0)

在这种情况下，你可以为每个移动 SDK 文档使用不同的文档插件实例。

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

警告

如果每个文档实例都非常大，你应该创建 2 个不同的 Docusaurus 站点。

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

如果有人编辑了 iOS 文档，那么重建所有内容（包括整个未更改的 Android 文档）真的有用吗？

¥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

有时候，你希望对某些文档进行版本控制，而其他文档则比较 "global"，感觉对它们进行版本控制没什么用。

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

我们在 Docusaurus 网站本身上使用了这种模式：

¥We use this pattern on the Docusaurus website itself:

设置​

¥Setup

假设你有 2 个文档：

¥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.

警告

@docusaurus/preset-classic 已经为你提供了一个文档插件实例！

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

使用预设时：

¥When using the preset:

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // id: 'product', // omitted => default instance
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: './sidebarsProduct.js',
          // ... other options
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... other options
      },
    ],
  ],
};

不使用预设时：

¥When not using the preset:

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // omitted => default instance
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: './sidebarsProduct.js',
        // ... other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... other options
      },
    ],
  ],
};

不要忘记为插件实例分配唯一的 id 属性。

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

注意

我们认为 product 实例是最重要的实例，并通过不分配任何 ID 将其设为 "default" 实例。

¥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 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

其他插件实例（具有 id 属性）将使用这些路径：

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

  • website/[pluginId]_versions.json

  • website/[pluginId]_versioned_docs

  • website/[pluginId]_versioned_sidebars

提示

你可以省略文档插件实例之一的 id 属性（默认为 default）。

¥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

每个插件实例都有自己的 CLI 命令来标记新版本。如果你运行以下命令，它们将会显示：

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

npm run docusaurus -- --help

要对产品/默认文档插件实例进行版本控制：

¥To version the product/default docs plugin instance:

npm run docusaurus docs:version 1.0.0

要对非默认/社区文档插件实例进行版本控制：

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

npm run docusaurus docs:version:community 1.0.0

文档导航栏项目​

¥Docs navbar items

每个与文档相关的 主题导航栏项目 都采用可选的 docsPluginId 属性。

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

例如，如果你希望每个移动 SDK（iOS 和 Android）都有一个版本下拉列表，你可以执行以下操作：

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

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};