跳到主要内容

多个文档插件实例

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.

使用场景​

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

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

移动端 SDK 文档​

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

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

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

警告

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

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

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

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

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

设置​

假设我们有两份文档：

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

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

警告

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

备注

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

版本化的路径​

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

默认实例使用以下路径：

  • 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

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

npm run docusaurus docs:version 1.0.0

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

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