版本控制

您可以使用版本控制 CLI 基于 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`	当前	/docs/next/hello

提示

docs 目录中的文件属于“当前”文档版本。

默认情况下，“当前”文档版本标记为“Next”，并托管在 /docs/next/* 下，但它完全可以配置以适应项目的发布周期。

术语

请注意我们在此处使用的术语。

当前版本: 位于 ./docs 文件夹中的版本。
最新版本: 默认情况下为文档导航栏项目提供的版本。通常路径为 /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-[versionName]/ 文件夹中。
根据您当前的侧边栏配置（如果存在）创建一个版本化侧边栏文件——保存为 versioned_sidebars/version-[versionName]-sidebars.json。
将新的版本号添加到 versions.json 中。

创建新文档

将新文件放入相应的版本文件夹中。
根据版本号在相应的侧边栏文件中包含对新文件的引用。

Current version structure
Older version structure

# 新文件。
docs/new.md

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

# 新文件。
versioned_docs/version-1.0.0/new.md

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

提示

版本化侧边栏文件与标准侧边栏文件一样，相对于给定版本的content根目录——因此对于上面的示例，您的版本化侧边栏文件可能如下所示：

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

或者对于手动侧边栏：

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

更新现有版本

您可以同时更新多个文档版本，因为 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.0），您可以考虑通过赋予它路径和标签来“假装”当前版本是一个剪切版本：

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 路由）引用。
- 提示：如果您的当前版本指的是一个不断修补和发布的主要版本，则 lastVersion: 'current' 是有意义的。最新版本的实际路由基路径和标签是可配置的。
onlyIncludeVersions：定义要部署的 versions.json 中版本的子集。
- 提示：在开发和部署预览中限制为 2 或 3 个版本，以提高启动和构建速度。
versions：版本元数据的字典。对于每个版本，您可以自定义以下内容：
- label：在版本下拉菜单和横幅中显示的标签。
- path：此版本的路由基路径。默认情况下，最新版本为 /，当前版本为 /next。
- banner：'none'、'unreleased' 和 'unmaintained' 之一。确定在每个文档页面的顶部显示的内容。任何高于最新版本的版本都将是“未发布的”，任何低于最新版本的版本都将是“未维护的”。
- badge：在该版本文档的顶部显示带有版本名称的徽章。
- className：向该版本文档页面的 <html> 元素添加自定义 className。

有关更多详细信息，请参阅文档插件配置。

我们提供了一些导航栏项目，可以帮助您快速设置导航，而无需担心版本化路由。

doc ：指向文档的链接。
docSidebar ：指向侧边栏中第一个项目的链接。
docsVersion ：指向当前查看版本的文档主体的链接。
docsVersionDropdown ：包含所有可用版本的下拉菜单。

这些链接都将按照以下顺序查找合适的版本来链接：

活动版本 ：用户当前正在浏览的版本，如果用户位于此文档插件提供的页面上。如果用户不在文档页面上，则回退到……
首选版本 ：用户上次查看的版本。如果没有历史记录，则回退到……
最新版本 ：我们导航到的默认版本，由 lastVersion 选项配置。

推荐实践

仅在需要时才对文档进行版本控制

例如，您正在为您的 npm 包 foo 构建文档，您当前的版本是 1.0.0。然后，您发布了一个针对次要错误修复的补丁版本，现在是 1.0.1。

您应该创建新的文档版本 1.0.1 吗？ 您可能不应该。 根据语义版本控制，1.0.1 和 1.0.0 文档不应该有所不同，因为没有新功能！为其创建新版本只会创建不必要的重复文件。

保持版本数量较少

作为一个好的经验法则，尝试将您的版本数量保持在 10 个以下。您 很可能 会有许多过时的版本化文档，没有人再阅读它们了。例如， Jest 当前的版本为 27.4，并且只维护几个最新的文档版本，最低版本为 25.X。保持精简😊

archive older versions

如果您在 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 路径。文件将链接到正确的对应版本。

[@hello](hello.mdx#paginate) 文档很棒！

参见 [教程](../getting-started/tutorial.mdx) 了解更多信息。

全局或版本化并置资产

您应该决定图像和文件之类的资产是每个版本专用还是在版本之间共享。

如果您的资产应该进行版本控制，请将其放入文档版本中，并使用相对路径：

![img alt](./myImage.png)

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

如果您的资产是全局的，请将其放入 /static 中并使用绝对路径：

![img alt](/myImage.png)

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

概述​

术语​

教程​

标记新版本​

创建新文档​

更新现有版本​

删除现有版本​

配置版本控制行为​

导航栏项目​

推荐实践​

仅在需要时才对文档进行版本控制​

保持版本数量较少​

在文档中使用绝对导入​

通过文件路径链接文档​

全局或版本化并置资产​

概述

术语

教程