分版
你可以用分版命令,根据当前 docs
目录里的最 新内容,生成一个新文档版本。 然后,即使继续更改 docs
目录的文档,这一组文档仍然会被保留并且可以访问。
在给你的文档划分版本之前,请三思——贡献者可能会更难帮助改进文档!
大多数情况下,你不需要划分文档版本,这样不仅会延长构建时间,还会把你的代码复杂化。 版本化最适合于高流量,文档在版本之间快速变化的网站。 如果你的文档很少更改,请不要给你的文档划分版本。
为了深入了解版本化是怎么工作的,并查看它是否符合你的需要,你可以继续阅读下文。
概览
典型的版本化文档网站如下所示:
website
├── sidebars.json # 当前文档版本的侧边栏
├── docs # 当前文档版本的文档目录
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
│ └── hello.md # https://mysite.com/docs/next/hello
├── versions.json # 表明哪些版本可用的文件
├── versioned_docs
│ ├── version-1.1.0
│ │ ├── foo
│ │ │ └── bar.md # https://mysite.com/docs/foo/bar
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar
│ └── hello.md
├── versioned_sidebars
│ ├── version-1.1.0-sidebars.json
│ └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json
versions.json
文件是一个版本名称列表,按照最新到最旧排列。
下表解释了版本化的文件是如何从版本映射到生成的 URL 的。
路径 | 版本 | URL |
---|---|---|
versioned_docs/version-1.0.0/hello.md | 1.0.0 | /docs/1.0.0/hello |
versioned_docs/version-1.1.0/hello.md | 1.1.0(最新) | /docs/hello |
docs/hello.md | current | /docs/next/hello |
docs
目录里的文件属于 current
(当前)文档版本。
默认情况下,current
版本的标签为 Next
,会被放在 /docs/next/*
URL 路径下,但针对你的项目的发布周期,这些都可以定制。
术语
请注意我们在这里使用的术语。
- 当前版本
- The version placed in the
./docs
folder. - 最新版本
- The version served by default for docs navbar items. Usually has path
/docs
.
当前版本是由文件系统位置定义的,而最新版本是由导航行为定义的。 它们可 能是同一个版本,也可能不是同一个版本! (而且按照上面的表格给出的配置,它们默认情况下确实是不一样的:当前版本会有 /docs/next
路径,而最新版本会有 /docs
路径。)
教程
标记新版本
- 首先,确保当前文档版本(
./docs
目录)已经准备好被冻结。 - 输入新的版本号。
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.1.0
yarn docusaurus docs:version 1.1.0
pnpm run docusaurus docs:version 1.1.0
标记新版本时,文档分版机制会:
- 把
docs/
文件夹整个复制到新的versioned_docs/version-[版本名]/
文件夹。 - Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as
versioned_sidebars/version-[versionName]-sidebars.json
. - 把新版本号添加到
versions.json
开头。
创建新文档
- 把新文件放在相应版本的文件夹中。
- 根据版本号,在相应的侧边栏文件中添加新文件的引用。
- 当前版本结构
- 较旧版本结构
# 新文件。
docs/new.md
# 编辑相应的侧边栏文件。
sidebars.js
# 新文件。
versioned_docs/version-1.0.0/new.md
# 编辑相应的侧边栏文件。
versioned_sidebars/version-1.0.0-sidebars.json
Versioned sidebar files are, like standard sidebar files, relative to the content root for the given version — so for the example above, your versioned sidebar file may look like:
{
"sidebar": [
{
"type": "autogenerated",
"dirName": "."
}
]
}
or for a manual sidebar:
{
"sidebar": [
{
"type": "doc",
"id": "new",
"label": "New"
}
]
}
更新现有版本
你可以同时更新多个文档版本,因为 versioned_docs/
下的每一个目录都会在发布时变成特定的路径。
- 编辑任何文件。
- 提交并推送更改。
- 它会被发布到对应版本。
比如,如果你修改了 versioned_docs/version-2.6/
下的任何文件,都只会影响 2.6
版本的文档。
删除现有版本
你也可以删除版本。
- 从
versions.json
中删除版本名。
示例:
[
"2.0.0",
"1.9.0",
- "1.8.0"
]
- 删除版本化文档目录。 比如:
versioned_docs/version-1.8.0
。 - 删除版本化侧边栏文件。 比如:
versioned_sidebars/version-1.8.0-sidebars.json
。