多个文档插件实例

优质

小牛编辑

130浏览

2023-12-01

@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 网站就使用了这种模式：

https://www.xnip.cn/doc/ZMAUaeSd* 部分实行版本化
/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

yarn run docusaurus -- --help

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

npm
Yarn

npm run docusaurus docs:version 1.0.0

yarn run docusaurus docs:version 1.0.0

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

npm
Yarn

npm run docusaurus docs:version:community 1.0.0

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