跳到主要内容

版本化管理

你可以使用 version 命令基于 docs 目录下的最新内容来创建新的文档版本。即使 docs 目录下的文档在不断被修改,该新创建的文档版本将被保留下来并可以永久访问。

caution

在开始对文档进行版本化管理之前,你要先明白:这将为帮助你改善文档的贡献者增加难度!

大多数时候,你不需要版本化管理,因为这只会增加网站的构建时间,并给代码库带来复杂性。版本化管理 最适合访问量高且各版本的文档之间变化很快的网站. 如果你的文档很少有更改,请不要为文档使用版本化管理。

为了更好地理解版本化管理的工作原理以及思考是否满足你的需求,请阅读以下内容。

目录结构#

website
├── sidebars.json # sidebar for master (next) version
├── docs # docs directory for master (next) version
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
│ └── hello.md # https://mysite.com/docs/next/hello
├── versions.json # file to indicate what versions are available
├── 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

下面的表格说明了版本化的文件是如何映射到其版本号的以及如何映射到为其生成的 URL 的。

PathVersionURL
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 (latest)/docs/hello
docs/hello.mdnext/docs/next/hello

标记新版本#

  1. 首先,请确保你在 docs 目录下的内容已经为创建一个新版本做好了准备。所有版本都是基于 master 分支上的内容生成的。
  2. 确定一个新的版本号
npm run docusaurus docs:version 1.1.0

当标记一个新版本时,文档的版本化控制机制将:

  • docs/ 目录下完整的内容复制到新的 versioned_docs/version-<version>/ 目录下。
  • 将当前的 侧边栏 配置文件(如果存在的话)作为母版,创建一个带有版本号的侧边栏配置文件,并保存为 versioned_sidebars/version-<version>-sidebars.json 文件。
  • versions.json 文件中添加新的版本号。

关于文档#

创建新文档#

  1. 将新文件放入相应的带版本号的目录下。
  2. 根据版本号,将新文件添加到该版本相对应的侧边栏配置文件中。

为 Master 分支上的文档添加新文件

# The new file.
docs/new.md
# Edit the corresponding sidebar file.
sidebar.js

为旧版本的文档添加新文件

# The new file.
versioned_docs/version-1.0.0/new.md
# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json

链接文档#

  • 请记住要包含 .md 扩展名。
  • 文件将被链接至正确的版本
  • 可以使用相对路径。
The [@hello](hello.md#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.md) for more info.

关于版本#

versioned_docs/ 中的每个目录都代表了一个文档版本。

更新现有版本#

你可以同时更新多个文档版本,因为 versioned_docs/ 下的每个目录都对应着特定的路由。

  1. 编辑任何文件。
  2. 提交并推送你所做的更改。
  3. 你所做的更改就发布到该版本了。

例如:当你在 versioned_docs/version-2.6/ 目录下修改任何文件时,只会影响 2.6 版本的文档。

删除现有版本#

你可以删除某个或某些版本。

  1. versions.json 文件中删除该版本。

Example:

[
"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

推荐做法#

弄清楚 "current" 版本的本质#

"current" 版本是 ./docs 目录的版本号。

目前有多种不同的版本管理的方式,但是其中两种非常常见:

  • 当你发布了 v1 版本,并立即着手开发 v2 版本(包括其文档)
  • 当你发布了 v1 版本,在考虑开发 v2 版本钱,会维护 v1 版本一段时间.

Docusaurus 的默认设计非常适合第一种方式。

对于第二中方式:如果你发布了 v1 版本,并且不打算很快开发 v2 版本的话,那么你无需对 v1 版本进行版本化管理,但是必须将文档保存在 2 个文件夹中(即 ./docs + ./versioned_docs/version-1.0.0),那么你可以考虑改用以下设置:

{
"lastVersion": "current",
"versions": {
"current": {
"label": "1.0.0",
"path": "1.0.0"
}
}
}

./docs 目录下的文档的 URL 是 /docs/1.0.0,而不是 /docs/next,而 1.0.0 将成为我们在导航条下拉菜单中列出的默认版本,因此,你只需要维护一个 ./docs 目录即可。

有关更多信息请参见 文档插件的配置

仅在需要的时候对文档进行版本化管理#

例如,你正在为 npm 软件包 foo 编纂文档,并且当前版本为 1.0.0。后来,你因为修补了一些小 bug 而发布了一个 1.0.1 版本。

你是否应该创建一个 1.0.1 版本的文档呢?可能不应该。根据语义化版本(semver)的定义,1.0.1 和 1.0.0 版本之间没有新增任何新功能,所以文档不应该有所不同。为其创建一份单独的版本化文档只会增加不必要的冗余。

保持较少的版本数量#

作为一个很好的经验法则,请尝试将版本数量保持在 10 以下。很有可能 你的许多版本的文档都已经过时了,甚至没有人再去阅读了。例如,Jest 当前的版本为 24.9,并且仅维护几个最新(不低于 22.X)版本的文档。少即好 😊

在文档中使用 import 时要使用绝对路径#

在文档中使用 import 时,不要使用相对路径。因为当我们创建了一个新版本时,原来的相对路径就不成立了(目录的嵌套级别不同了,以及其它原因)。你可以使用 Docusaurus 提供的 @site 别名,该别名指向 website 目录。例如:

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

静态资源是共用还是版本化#

你应该决定类似图片之类的静态资源是分版本放置还是所有版本共用

如果你的静态资源应当版本化,那么请将其与版本化的文档放在一起,并使用相对路径来引用:

![img alt](./myImage.png)
[download this file](./file.pdf)

如果你的静态资源是所有版本共用的,则将其放到 /static 目录先,并使用绝对路径来引用:

![img alt](/myImage.png)
[download this file](/file.pdf)