版本化管理

优质

小牛编辑

134浏览

2023-12-01

你可以使用 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 的。

Path	Version	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 (latest)	/docs/hello
`docs/hello.md`	next	/docs/next/hello

标记新版本

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

npm
Yarn

npm run docusaurus docs:version 1.1.0

yarn run docusaurus docs:version 1.1.0

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

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

关于文档

创建新文档

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

为 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/ 下的每个目录都对应着特定的路由。

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

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

删除现有版本

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

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

Example:

[
  "2.0.0",
  "1.9.0",
- "1.8.0"

]

删除带版本号的文档目录。例如：versioned_docs/version-1.8.0。
删除带版本号的侧边栏配置文件。例如：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）版本的文档。少即好