文档多实例

@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', // 省略 => 默认实例
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: './sidebarsProduct.js',
          // ... 其他选项
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... 其他选项
      },
    ],
  ],
};

不使用预设时：

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // 省略 => 默认实例
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: './sidebarsProduct.js',
        // ... 其他选项
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
        // ... 其他选项
      },
    ],
  ],
};

不要忘记为插件实例分配唯一的 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

npm run docusaurus -- --help

Yarn

yarn docusaurus --help

pnpm

pnpm run docusaurus --help

要对 product/default 文档插件实例进行版本控制：

npm

npm run docusaurus docs:version 1.0.0

Yarn

yarn docusaurus docs:version 1.0.0

pnpm

pnpm run docusaurus docs:version 1.0.0

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

npm

npm run docusaurus docs:version:community 1.0.0

Yarn

yarn docusaurus docs:version:community 1.0.0

pnpm

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