第9章 Docusaurus 文档多实例配置

Version: 2.xDocs Multi-instance @docusaurus/plugin-content-docs 插件支持多实例。 注意：这个功能只对版本化文档有用。阅读本页前建议先了解 docs versioning。如果你只是想要多个侧边栏，在单个插件内就能实现。 适用场景 有时你可能想让一个 Docusaurus 站点承载 2 套（或更多）相互独立的文档。 这些文档甚至可能有不同的版本管理和发布周期。 移动 SDK 文档 如果你在开发跨平台移动 SDK，可能会有 2 套文档： - Android SDK 文档（v1.0、v1.1） - iOS SDK 文档（v1.0、v2.0） 这种情况下，你可以为每个移动 SDK 文档分别使用一个 docs 插件实例。 警告：如果每套文档都非常庞大，建议创建 2 个独立的 Docusaurus 站点。有人编辑 iOS 文档时，真的有必要重新构建整个站点，包括完全没变的 Android 文档吗？ 版本化与未版本化文档 有时你希望一部分文档有版本管理，而另一部分文档偏"全局性"，给它们做版本管理没什么意义。 Docusaurus 官网本身就采用了这种模式： - /docs/* 部分有版本管理 - /community/* 部分没有版本管理 配置方法 假设你有 2 套文档： - Product：关于你产品的版本化文档 - Community：关于产品社区的未版本化文档 这种情况下，你需要在站点配置中把同一个插件配置两次。 警告：@docusaurus/preset-classic 已经内置了一个 docs 插件实例！ 使用 preset 时： docusaurus.config.jsmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// id: 'product', // 省略 => 默认实例
path: 'product',
routeBasePath: 'product',
sidebarPath: require.resolve('./sidebarsProduct.js'),
// ... 其他选项
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: require.resolve('./sidebarsCommunity.js'),
// ... 其他选项
},
],
],
};
不使用 preset 时： docusaurus.config.jsmodule.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 提示：你可以省略一个文档插件实例的 id 属性（默认为 default）。该实例的路径会更简洁，且与单实例配置向后兼容。 为新版本打标签​ 每个插件实例都有自己的 CLI 命令来为新版本打标签。运行以下命令即可查看： npmYarnpnpmBunnpm run docusaurus -- --help
yarn docusaurus --help
pnpm run docusaurus --help
bun run docusaurus --help
为 product/默认文档插件实例创建版本： npmYarnpnpmBunnpm run docusaurus docs:version 1.0.0
yarn docusaurus docs:version 1.0.0
pnpm run docusaurus docs:version 1.0.0
bun run docusaurus docs:version 1.0.0
为非默认的 community 文档插件实例创建版本： npmYarnpnpmBunnpm run docusaurus docs:version:community 1.0.0
yarn docusaurus docs:version:community 1.0.0
pnpm run docusaurus docs:version:community 1.0.0
bun run docusaurus docs:version:community 1.0.0
文档导航栏项​ 每个与文档相关的主题导航栏项都有一个可选的 docsPluginId 属性。 例如，如果你想为每个移动 SDK（iOS 和 Android）各设一个版本下拉菜单，可以这样做： docusaurus.config.jsmodule.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
这是纯代码片段，无翻译内容。直接原样输出： docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};