多个文档插件实例

@docusaurus/plugin-content-docs 插件可以有多个实例并存。

note

此功能仅对版本化文档有用。建议在阅读此章节前先熟悉文档版本化。

使用场景#

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

这些文档甚至可能具有不同的版本或发布周期。

移动端 SDK 文档#

如果你构建的是跨平台的移动端 SDK，则可能有两份文档：

Android SDK 文档 (v1.0, v1.1)
iOS SDK 文档 (v1.0, v2.0)

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

caution

如果每份文档的数量都很多，那么你应该创建两个不同的 Docusaurus 站点。

如果有人编辑了 iOS 文档，那么构建时还要捎带上 Android 文档，这不是浪费吗？

版本化和未版本化的文档#

有时，你希望对某些文档进行版本化管理，而其它文档则更具“全局化”，因此对这些文档进行版本化管理感觉毫无用处。

我们为 Docusaurus 网站就使用了这种模式：

/docs/* 部分实行版本化
/community/* 部分未版本化

设置#

假设我们有两份文档：

Product: 关于产品的版本化文档
Community: 围绕产品社区的未版本化的文档

在这种情况下，在站点的配置文件中你需要使用同一插件两次。

caution

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

使用预设的话：

docusaurus.config.js

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

不使用预设的话：

docusaurus.config.js

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

不要忘记为每个插件实例赋予一个唯一的 id 属性。

note

我们认为 product 实例是最重要的，通过不为其分配任何 id 从而使其成为“默认”实例。

版本化的路径#

每个实例会将版本化的文档存储在不同的文件夹中。

默认实例使用以下路径：

website/versions.json
website/versioned_docs
website/versioned_sidebars

其它实例（设置了 id 属性的实例）使用以下路径：

website/<pluginId>_versions.json
website/<pluginId>_versioned_docs
website/<pluginId>_versioned_sidebars

tip

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

该实例的路径就会变简单了，并且兼容单实例的设置。

标记新版本#

每个插件实例将拥有其自己的 cli 命令来标记新版本。运行后将显示：

npm
Yarn

npm run docusaurus -- --help

为 product/default 文档实例标记新版本：

npm
Yarn

npm run docusaurus docs:version 1.0.0

为非默认或 community 文档插件实例标记新版本：

npm
Yarn

npm run docusaurus docs:version:community 1.0.0

导航条上的文档菜单#

每个与文档相关的导航条菜单项都具有一个可选的 docsPluginId 属性。

例如，如果要为每个移动端 SDK（iOS 和 Android）提供一个版本下拉列表，则可以如下：

docusaurus.config.js

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};