Version: 3.7.0

版本控制

您可以使用版本控制CLI基于docs目录中的最新内容创建新的文档版本。这样，即使docs目录中的文档继续发展，这组特定的文档也将被保留并可访问。

warning

在开始对你的文档进行版本控制之前，请三思——这可能会使贡献者难以帮助改进它！

大多数情况下，你不需要版本控制，因为它只会增加你的构建时间，并给你的代码库引入复杂性。版本控制最适合那些流量大且文档在版本之间变化迅速的网站。如果你的文档很少变化，就不要给你的文档添加版本控制。

为了更好地理解版本控制的工作原理并查看它是否适合您的需求，您可以继续阅读以下内容。

概述

一个典型的版本化文档网站如下所示：

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs 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

versions.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`	current	/docs/next/hello

tip

docs 目录中的文件属于 current 文档版本。

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

术语

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

Current version: The version placed in the ./docs folder.
Latest version / last version: 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-[versionName]/文件夹中。
根据您当前的侧边栏配置（如果存在）创建一个版本化的侧边栏文件 - 保存为versioned_sidebars/version-[versionName]-sidebars.json。
将新版本号附加到versions.json。

创建新文档

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

当前版本结构
旧版本结构

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.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

tip

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

{
  "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: 为该版本的文档页面的元素添加自定义的 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提供的@site别名，它指向website目录。例如：

- 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.

全局或版本化的共置资产

您应该决定像图片和文件这样的资产是按版本划分还是在版本之间共享。

如果您的资产需要版本控制，请将它们放入文档版本中，并使用相对路径：

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

[download this file](./file.pdf)

如果你的资产是全局的，请将它们放在/static并使用绝对路径：

![img alt](/myImage.png)

[download this file](/file.pdf)

概述​

术语​

教程​

标记新版本​

创建新文档​

更新现有版本​

删除现有版本​

配置版本控制行为​

导航栏项目​

推荐实践​

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

保持版本数量较少​

在文档中使用绝对导入​

通过文件路径链接文档​

全局或版本化的共置资产​

概述

术语

教程