分版

你可以用分版命令，根据当前 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 路径下，但针对你的项目的发布周期，这些都可以定制。

术语

请注意我们在这里使用的术语。

当前版本（current version）

这个版本被置于 ./docs 文件夹。

最新版本（latest version / last version）

导航栏的文档类型项目会默认指向的版本。 通常会有路径 /docs。

当前版本是由文件系统位置定义的，而最新版本是由导航行为定义的。 它们可能是同一个版本，也可能不是同一个版本！ （而且按照上面的表格给出的配置，它们默认情况下确实是不一样的：当前版本会有 /docs/next 路径，而最新版本会有 /docs 路径。）

教程

标记新版本

1. 首先，确保当前文档版本（./docs 目录）已经准备好被冻结。
2. 输入新的版本号。

npm

npm run docusaurus docs:version 1.1.0

Yarn

yarn docusaurus docs:version 1.1.0

pnpm

pnpm run docusaurus docs:version 1.1.0

Bun

bun 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/version-1.0.0/new.md

# 编辑相应的侧边栏文件
versioned_sidebars/version-1.0.0-sidebars.json

提示

版本式侧边栏文件像标准侧边栏文件一样， 相对于给定版本的内容根目录，所以在上面的例子中，您的版本的侧边栏文件可能会看起来像：

{
  "sidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

或手动设置侧边栏：

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

更新现有版本

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

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

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

删除现有版本

你也可以删除版本。

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

示例：

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

2. 删除版本化文档目录。 比如：versioned_docs/version-1.8.0。
3. 删除版本化侧边栏文件。 比如： 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.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。

See docs plugin configuration for more details.

导航栏项目

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

• doc: a link to a doc.
• docSidebar: a link to the first item in a sidebar.
• docsVersion: a link to the main doc of the currently viewed version.
• docsVersionDropdown: a dropdown containing all the versions available.

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

1. Active version: the version that the user is currently browsing, if she is on a page provided by this doc plugin. 如果用户不在浏览文档页面，会回退到……
2. Preferred version: the version that the user last viewed. 如果没有历史记录，会回退到……
3. Latest version: the default version that we navigate to, configured by the lastVersion option.

推荐做法

按需分版文档

For example, you are building documentation for your npm package foo and you are currently in version 1.0.0. 你随后修了一个小 bug，发布了一个修复版本，版本号现在是 1.0.1 了。

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

保持有限的版本数量

一个好用的经验法则是，把版本数量保持在 10 以下。 You will very likely to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 27.4, and only maintains several latest documentation versions with the lowest being 25.X. 把版本弄少一点 😊

archive older versions

If you deploy your site on a Jamstack provider (e.g. Netlify), the provider will save each production build as a snapshot under an immutable URL. 你可以把那些再也不会重新构建的版本封存，然后以外部链接的形式指向这些不可变 URL。 Jest 网站和 Docusaurus 网站都使用这种模式，保持有限的活跃构建版本数量。

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

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

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

用文件路径链接文档

Refer to other docs by relative file paths with the .md extension, so that Docusaurus can rewrite them to actual URL paths during building. 文件会被链接到正确的对应版本。

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)