跳到主要内容

多个文档插件实例

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

设置#

假设我们有两份文档:

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