跳到主要内容
版本:Canary 🚧

分版

你可以用分版命令,根据当前 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.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0(最新)/docs/hello
docs/hello.mdcurrent/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 路径。)

教程

标记新版本

  1. 首先,确保当前文档版本(./docs 目录)已经准备好被冻结。
  2. 输入新的版本号。
npm run docusaurus docs:version 1.1.0

标记新版本时,文档分版机制会:

  • docs/ 文件夹整个复制到新的 versioned_docs/version-[版本名]/ 文件夹。
  • 根据你当前的侧边栏配置(如果有),创建一个版本化的侧边栏文件,并将它保存为 versioned_sidebars/version-[版本名]-sidebars.json
  • 把新版本号添加到 versions.json 开头。

创建新文档

  1. 把新文件放在相应版本的文件夹中。
  2. 根据版本号,在相应的侧边栏文件中添加新文件的引用。
# 新文件。
docs/new.md

# 编辑相应的侧边栏文件。
sidebars.js

更新现有版本

你可以同时更新多个文档版本,因为 versioned_docs/ 下的每一个目录都会在发布时变成特定的路径。

  1. 编辑任何文件。
  2. 提交并推送更改。
  3. 它会被发布到对应版本。

比如,如果你修改了 versioned_docs/version-2.6/ 下的任何文件,都只会影响 2.6 版本的文档。

删除现有版本

你也可以删除版本。

  1. versions.json 中删除版本名。

示例:

[
"2.0.0",
"1.9.0",
- "1.8.0"
]
  1. 删除版本化文档目录。 比如:versioned_docs/version-1.8.0
  2. 删除版本化侧边栏文件。 比如: versioned_sidebars/version-1.8.0-sidebars.json

配置版本行为

「当前」版本是 ./docs 文件夹中的版本。 版本管理的方式有很多种,但有两个非常常见的模式:

  • 你发布了 v1,然后立刻开始着手于 v2(包括其文档)。 在这种情况下,当前版本是 v2, 它在 ./docs 文件夹中,并且可以在 example.com/docs/next 浏览。 最新版本是 v1,它在 ./versioned_docs/version-1 文件夹中,在 example.com/docs 被大多数用户浏览。
  • 你发布了 v1,并会维护它一段时间,然后再考虑 v2。 在这种情况下,当前版本最新版本都会指向 v1,因为 v2 文档还不存在呢!

Docusaurus 的默认设置更适合第一种情形。 我们会把当前版本标为「下一版本」(next),你甚至可以选择不发布它。

对于第二种情形:你发布了 v1,并且没有开始着手于 v2 的计划。此时,你不应该给 v1 划分版本,然后同时维护两个目录里的文档(./docs + ./versioned_docs/version-1.0)。你可以考虑给当前版本一个 URL 路径和一个标签,「假装」它是一个划分出的版本:

docusaurus.config.js
export default {
presets: [
'@docusaurus/preset-classic',
docs: {
lastVersion: 'current',
versions: {
current: {
label: '1.0.0',
path: '1.0.0',
},
},
},
],
};

./docs 中的文档会被发布在 /docs/1.0.0 路径上,而不是 /docs/next,并且导航栏菜单会默认链接到 1.0.0 版本,这样你就只需要维护 ./docs 一个文件夹了。

我们提供这些插件选项来自定义版本行为:

  • disableVersioning: 即使网站有其他版本的文档,也明确禁用版本控制。 这会让网站只包含当前版本。
  • includeCurrentVersion: 在发布时包含当前版本(./docs 文件夹)。
    • 提示:如果当前版本文档还在创作,尚未准备好发布,请关闭此选项。
  • lastVersion: 设置「最新版本」(/docs URL 路径)代表哪个版本。
    • 提示:如果你的当前版本指向的是一个在不停修复和发布的大版本,lastVersion: 'current' 会比较合理。 最新版本的实际 URL 路径前缀和标签都是可以设置的。
  • onlyIncludeVersions: 定义了 versions.json 里的哪些版本应该被部署。
    • 提示:在开发模式和部署预览中限制为 2 到 3 个版本,可以改善启动和构建时间。
  • versions: 版本元数据的字典。 对于每个版本,你可以自定义以下内容:
    • label: 版本下拉菜单和横幅上显示的标签。
    • path: 此版本的路径前缀。 默认情况下,最新版本的前缀为 /,而当前版本的前缀为 /next
    • banner: 'none''unreleased''unmaintained' 中的一个。 决定每个文档页面的顶部显示什么横幅。 所有在最新版本之后的版本都是「未发布」("unreleased"),而在最新版本之前的版本都是「停止维护」("unmaintained")。
    • badge: 在此版本的文档开头显示一个版本名标记。
    • className: 为此版本的文档页面的 <html> 元素添加一个自定义 className

文档插件配置文档 中有更多信息可供了解。

我们提供了几种导航栏项目,可以帮助你快速设置导航,不需要操心版本化的路径。

  • doc:链接到某篇文档。
  • docSidebar:链接到某个侧边栏的第一个项目。
  • docsVersion: a link to the main doc of the currently viewed version.
  • docsVersionDropdown: a dropdown containing all the versions available.

这些链接都会自动寻找自己应该指向的版本,按照如下优先级:

  1. 活跃版本:如果用户正在浏览这个文档插件提供的某个页面,会指向这个页面所属的版本。 如果用户不在浏览文档页面,会回退到……
  2. 偏好版本:用户上一次浏览的版本。 如果没有历史记录,会回退到……
  3. 最新版本:默认会跳转到的版本。可以通过 lastVersion 设置。

按需分版文档

举个例子,你在为你的某个 npm 包编写文档,而你现在的版本是 1.0.0。 你随后修了一个小 bug,发布了一个修复版本,版本号现在是 1.0.1 了。

你应该发布新的 1.0.1 版本文档吗? 你大概率不应该。 按照语义化版本规范,1.0.1 和 1.0.0 的文档不应该有区别,因为没有新功能! 这时候划分新版本只会创造不必要的重复文件。

保持有限的版本数量

一个好用的经验法则是,把版本数量保持在 10 以下。 你的很多文档版本很可能已经过时了,没有人会再读它们了。 比如,Jest 现在的版本是 27.4,并且只维护过往若干版本的文档,最老的版本是 25.X。 把版本弄少一点 😊

封存更老的版本

如果你的网站部署在某个 Jamstack 服务商上(比如 Netlify),那么服务商会把每次生产构建保存成一个快照,并且放在一个不可变的 URL 上。 你可以把那些再也不会重新构建的版本封存,然后以外部链接的形式指向这些不可变 URL。 Jest 网站和 Docusaurus 网站都使用这种模式,保持有限的活跃构建版本数量。

在文档中使用绝对路径导入

不要在文档中使用相对路径导入。 因为当我们划分版本后,这些路径就不再起作用了(因为文件夹嵌套层级不一样了,等等)。 你可以用 Docusaurus 提供的指向 website 目录的 @site 别名。 示例:

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

在引用其他文档时,使用包含 .md 扩展名的相对文件路径,这样 Docusaurus 可以在构建过程中把它们重写为实际的 URL 路径。 文件会被链接到正确的对应版本。

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

全局或版本化的共享资源

你需要决定像图像和文件这样的资源是每个版本专有的,还是在版本之间共享。

如果你的资源是和版本相关的,把它们放在版本文件夹中,并使用相对路径:

![图片 alt](./myImage.png)

[下载此文件](./file.pdf)

如果你的资源是全局的,把它们放在 /static 下,并使用绝对路径:

![图片 alt](/myImage.png)

[下载此文件](/file.pdf)