文档多实例

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

备注

此特性仅对版本化文档有用。建议在阅读此页之前熟悉文档版本控制。如果你只想要多个侧边栏，你可以在一个插件中完成。

用例

有时候，你希望 Docusaurus 网站能够承载两组不同的文档(或者更多)。

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

移动 SDKs 文档

如果你构建一个跨平台的移动 SDK，你可能有 2 个文档:

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

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

警告

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

如果有人编辑了 iOS 文档，那么重新构建所有内容(包括未更改的整个 Android 文档)是否真的有用?

版本和未版本文档

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

我们在 Docusaurus 网站上使用了这种模式:

• /docs/* 节是有版本的
• /community/* 节未进行版本控制

设置

假设你有两个文档:

• Product: 一些关于你的产品的版本文档
• Community: 一些关于你产品周围社区的未版本文档

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

警告

@docusaurus/preset-classic已经为你包含了一个 docs 插件实例!

使用预设时:

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 使其成为默认实例。

版本化路径

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

默认的插件实例将使用这些路径:

• website/versions.json
• website/versioned_docs
• website/versioned_sidebars

其他插件实例(带有id属性)将使用这些路径:

• website/[pluginId]_versions.json
• website/[pluginId]_versioned_docs
• website/[pluginId]_versioned_sidebars

提示

你可以省略一个 docs 插件实例的id属性(默认为default)。

实例路径将更简单，并且与单实例设置向后兼容。

标记新版本

每个插件实例都有自己的 CLI 命令来标记新版本。如果您执行以下命令，将显示它们:

npm

npm run docusaurus -- --help

Yarn

yarn docusaurus --help

pnpm

pnpm run docusaurus -- --help

要对 product/default docs 插件实例进行版本化:

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

要 non-default/community docs 插件实例:

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

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