Skip to main content
Version: 2.x

文档多实例

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

note

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

使用案例​

有时你可能希望一个Docusaurus网站托管两组不同的文档（或更多）。

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

移动SDK文档​

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

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

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

warning

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

如果有人编辑了iOS文档，真的有必要重新构建所有内容，包括没有变化的整个Android文档吗？

版本化和非版本化文档​

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

我们在Docusaurus网站本身上使用这种模式：

设置​

假设你有2个文档：

  • 产品：关于您产品的某些版本化文档
  • 社区：一些关于您产品周围社区的未版本化文档

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

warning

@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

你可以省略其中一个docs插件实例的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
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};