Skip to main content

文档多实例

道格龙（Docusaurus）的 @docusaurus/plugin-content-docs 插件支持多实例。

note

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

使用场景​

有时，你可能希望一个道格龙（Docusaurus）网站能够托管两个或更多个不同的文档集。

这些文档集甚至可以有不同的版本控制和发布周期。

移动端 SDK 文档​

如果你在构建一个跨平台的移动端 SDK，你可能会有两套文档：

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

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

warning

如果每个文档实例都非常庞大，那么更好的做法是创建两个独立的道格龙（Docusaurus）网站。

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

版本化与非版本化文档​

有时，你可能希望对某些文档进行版本控制，而另一些文档则更具"全局性"，对它们进行版本控制似乎没有必要。

我们在道格龙（Docusaurus）自己的官网上就使用了这种模式：

设置​

假设你有两套文档：

  • 产品：关于你产品的版本化文档
  • 社区：关于你产品社区的非版本化文档

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

warning

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

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