多个文档插件实例
@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 网站就使用了这种模式:
- /docs/* 部分实行版本化
- /community/* 部分未版本化
#
设置假设我们有两份文档:
- Product: 关于产品的版本化文档
- Community: 围绕产品社区的未版本化的文档
在这种情况下,在站点的配置文件中你需要使用同一插件两次。
caution
@docusaurus/preset-classic
已经包含了一个文档插件的实例了!
使用预设的话:
不使用预设的话:
不要忘记为每个插件实例赋予一个唯一的 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
为 product/default 文档实例标记新版本:
- npm
- Yarn
为非默认或 community 文档插件实例标记新版本:
- npm
- Yarn
#
导航条上的文档菜单每个与文档相关的 导航条菜单项 都具有一个可选的 docsPluginId
属性。
例如,如果要为每个移动端 SDK(iOS 和 Android)提供一个版本下拉列表,则可以如下: