文档多实例
The @docusaurus/plugin-content-docs
plugin can support multi-instance.
使用场景
有时候,你想要用 Docusaurus 部署两套(或更多)完全不同的文档。
这些文档甚至可能有着不同的版本/发行周期。
移动设备 SDK 文档
如果你正为某个跨平台的移动设备 SDK 撰写文档,你可能会有以下两套文档:
- 安卓 SDK 文档(
v1.0
、v1.1
) - iOS SDK 文档(
v1.0
、v2.0
)
这种情况下,你可以为每个平台的 SDK 文档使用独立的文档插件实例。
如果每个插件实例的文档都非常庞大,你应该考虑创建两个 Docusaurus 站点。
假设有人编辑了 iOS 的文档,这时候真的有必要同时重新构建未修改的 Android 文档吗?
分版及未分版文档
有时候,你需要为某些文档划分版本,而其他文档则更为「全局」,没有必要给它们划分版本。
我们在 Docusaurus 网站上就使用了这种模式:
- /docs/* 部分存在多个版本
- /community/* 部分不分版本
设置
假设你有两套文档:
- 产品:划分了版本的产品文档
- 社区:单一版本的社区文档
这种情况下,你应该在站点配置中把同一个插件使用两次。
@docusaurus/preset-classic
已经自带了一个文档插件实例!
如果使用了预设:
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
],
};
如果不使用预设:
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './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 命令。 你可以运行下面的指令显示它们:
- npm
- Yarn
- pnpm
npm run docusaurus -- --help
yarn docusaurus --help
pnpm run docusaurus --help
要为产品(默认)文档插件实例添加版本:
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.0.0
yarn docusaurus docs:version 1.0.0
pnpm run docusaurus docs:version 1.0.0
要为社区(非默认)文档插件实例添加版本:
- npm
- Yarn
- pnpm
npm 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
文档导航栏项目
Each docs-related theme navbar items take an optional docsPluginId
attribute.
比如,如果你想要为每个移动 SDK(iOS 和 Android)添加一个版本下拉框,你可以这么做:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};