跳到主要内容
版本：3.8.1

文档多实例

@docusaurus/plugin-content-docs 插件支持多实例。

注意

此功能仅适用于版本化文档。建议您在阅读本页之前熟悉文档版本控制。如果您只是想要多个侧边栏，您可以在一个插件内实现。

用例​

有时您希望一个 Docusaurus 站点托管两套独立的文档（或更多）。

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

移动 SDK 文档​

如果您构建一个跨平台移动 SDK，您可能会有两套文档

  • Android SDK 文档（v1.0, v1.1）
  • iOS SDK 文档（v1.0, v2.0）

在这种情况下，您可以为每个移动 SDK 文档使用一个独立的文档插件实例。

警告

如果每个文档实例都非常大，您应该创建两个独立的 Docusaurus 站点。

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

版本化和非版本化文档​

有时，您希望某些文档进行版本控制，而其他文档则更“全局”，对其进行版本控制感觉毫无用处。

Docusaurus 官网本身就使用了这种模式

  • /docs/* 部分是版本化的
  • /community/* 部分是非版本化的

设置​

假设您有两套文档

  • 产品：一些关于您产品的版本化文档
  • 社区：一些关于您产品社区的非版本化文档

在这种情况下，您应该在站点配置中两次使用同一个插件。

警告

@docusaurus/preset-classic 已经为您包含了一个文档插件实例！

使用预设时

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
      },
    ],
  ],
};

不使用预设时

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 属性。

注意

我们认为 product 实例是最重要的一个，并且通过不分配任何 ID 来使其成为“默认”实例。

版本化路径​

每个插件实例都将版本化文档存储在独立的文件夹中。

默认插件实例将使用这些路径

  • website/versions.json
  • website/versioned_docs
  • website/versioned_sidebars

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

  • website/[pluginId]_versions.json
  • website/[pluginId]_versioned_docs
  • website/[pluginId]_versioned_sidebars
提示

您可以省略其中一个文档插件实例的 id 属性（默认为 default）。

实例路径将更简单，并且与单实例设置向后兼容。

标记新版本​

每个插件实例都将拥有自己的 CLI 命令来标记新版本。当您运行以下命令时，它们将显示出来

npm run docusaurus -- --help

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

npm run docusaurus docs:version 1.0.0

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

npm run docusaurus docs:version:community 1.0.0

文档导航栏项目​

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

例如，如果您想为每个移动 SDK（iOS 和 Android）设置一个版本下拉菜单，您可以这样做

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