版本控制

你可以使用版本控制 CLI，基于 docs 目录中的最新内容创建一个新的文档版本。这套特定的文档将被保存下来并可供访问，即便 docs 目录中的文档在不断演进。

注意

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

大多数情况下，你并不需要版本控制，因为它只会增加你的构建时间，并给你的代码库引入复杂性。版本控制最适用于那些流量大、版本间文档变更频繁的网站。如果你的文档很少变动，就不要为其添加版本控制。

为了更好地理解版本控制的工作原理，并判断它是否符合你的需求，你可以继续阅读下文。

概述

一个典型的版本化文档网站结构如下：

website
├── sidebars.json        # 当前文档版本的侧边栏
├── docs                 # 当前文档版本的 `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。

路径（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 (最新)	/docs/hello
`docs/hello.md`	开发版 (current)	/docs/next/hello

提示

docs 目录中的文件属于 current（开发版）文档版本。

默认情况下，current（开发版）文档版本被标记为 Next，并托管在 /docs/next/* 路径下，但这完全可以根据你项目的发布周期进行配置。

术语

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

开发版本 (Current version): 位于 `./docs` 文件夹中的版本。
最新版本 / 最近版本 (Latest version / last version): 文档导航栏项目默认服务的版本。通常路径为 `/docs`。

"开发版本"是由文件系统位置定义的，而"最新版本"是由导航行为定义的。它们可能相同，也可能不同！（如上表所示，默认配置将它们视为不同的版本：开发版本位于 /docs/next，最新版本位于 /docs。）

教程

标记新版本

首先，确保当前的文档版本（开发版）（即 ./docs 目录）已经准备好可以正式发布了。
输入一个新的版本号。

npm
Yarn
pnpm
Bun

npm run docusaurus docs:version 1.1.0

yarn docusaurus docs:version 1.1.0

pnpm run docusaurus docs:version 1.1.0

bun 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

提示

版本化的侧边栏文件和标准的侧边栏文件一样，其路径是相对于给定版本的内容根目录的——因此，对于上面的例子，你的版本化侧边栏文件可能看起来像这样：

{
  "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 之一。决定了每个文档页面顶部显示的内容。任何高于最新版本的版本都将是"未发布（unreleased）"，任何低于最新版本的版本都将是"未维护（unmaintained）"。
- badge：在该版本的文档顶部显示一个带有版本名称的徽章。
- className：为该版本文档页面的 <html> 元素添加一个自定义的 className。

更多详情请参阅文档插件配置。

我们提供了几种文档导航栏项目，帮助你快速设置导航，而无需担心版本化的路由。

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

这些链接都会按照以下顺序寻找合适的版本进行链接：

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

`docsVersionDropdown`

默认情况下，docsVersionDropdown 会显示一个包含所有可用文档版本的下拉菜单。

versions 属性允许你按给定顺序显示可用文档版本的子集：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          versions: ['current', '3.0', '2.0'],
        },
      ],
    },
  },
};

传递一个 versions 对象，可以让你覆盖每个版本的显示标签：

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          versions: {
            current: {label: '版本 4.0'},
            '3.0': {label: '版本 3.0'},
            '2.0': {label: '版本 2.0'},
          },
        },
      ],
    },
  },
};

版本控制

概述

术语

教程

标记新版本

创建新文档

更新现有版本

删除现有版本

配置版本控制行为

导航栏项目

`docsVersionDropdown`

推荐实践

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

保持少量版本

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

通过文件路径链接文档

全局或版本化的本地资源

概述​

术语​

教程​

标记新版本​

创建新文档​

更新现有版本​

删除现有版本​

配置版本控制行为​

导航栏项目​

docsVersionDropdown​

推荐实践​

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

保持少量版本​

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

通过文件路径链接文档​

全局或版本化的本地资源​

概述

术语

教程

标记新版本

创建新文档

更新现有版本

删除现有版本

配置版本控制行为

导航栏项目

`docsVersionDropdown`

推荐实践

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

保持少量版本

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

通过文件路径链接文档

全局或版本化的本地资源