版本：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.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-[版本名]/ 文件夹。
根据你当前的侧边栏配置（如果有），创建一个版本化的侧边栏文件，并将它保存为 versioned_sidebars/version-[版本名]-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_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。

配置版本行为

「当前」版本是 ./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.

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

活跃版本：如果用户正在浏览这个文档插件提供的某个页面，会指向这个页面所属的版本。如果用户不在浏览文档页面，会回退到……
偏好版本：用户上一次浏览的版本。如果没有历史记录，会回退到……
最新版本：默认会跳转到的版本。可以通过 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)

分版

概览​

术语​

教程​

标记新版本​

创建新文档​

更新现有版本​

删除现有版本​

配置版本行为​

导航栏项目​

推荐做法​

按需分版文档​

保持有限的版本数量​

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

用文件路径链接文档​

全局或版本化的共享资源​

概览

术语

教程