版本控制

¥Versioning

你可以使用版本控制 CLI 根据 docs 目录中的最新内容创建新的文档版本。即使 docs 目录中的文档不断发展，该特定文档集也将被保留并可访问。

¥You can use the versioning CLI to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory continues to evolve.

警告

在开始对文档进行版本控制之前请考虑一下 - 贡献者可能很难帮助改进它！

¥Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!

大多数时候，你不需要版本控制，因为它只会增加构建时间，并增加代码库的复杂性。版本控制最适合流量大且版本之间文档更改快速的网站。如果你的文档很少更改，请不要向文档添加版本控制。

¥Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

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

¥To better understand how versioning works and see if it suits your needs, you can read on below.

概述

¥Overview

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

¥A typical versioned doc site looks like below:

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 文件是版本名称列表，按从最新到最旧的顺序排列。

¥The versions.json file is a list of version names, ordered from newest to oldest.

下表说明了版本控制文件如何映射到其版本和生成的 URL。

¥The table below explains how a versioned file maps to its version and the generated 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 文档版本。

¥The files in the docs directory belong to the current docs version.

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

¥By default, the current docs version is labeled as Next and hosted under /docs/next/*, but it is entirely configurable to fit your project's release lifecycle.

术语

¥Terminology

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

¥Note the terminology we use here.

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。）

¥Current version is defined by the file system location, while latest version is defined by the the navigation behavior. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next and latest at /docs.)

教程

¥Tutorials

标记新版本

¥Tagging a new version

1. 首先，确保当前的文档版本（./docs 目录）已准备好冻结。

   ¥First, make sure the current docs version (the ./docs directory) is ready to be frozen.

2. 输入新的版本号。

   ¥Enter a new version number.

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

当标记新版本时，文档版本控制机制将：

¥When tagging a new version, the document versioning mechanism will:

• 将完整的 docs/ 文件夹内容复制到新的 versioned_docs/version-[versionName]/ 文件夹中。

  ¥Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder.

• 根据当前 sidebar 配置创建版本化侧边栏文件（如果存在） - 另存为 versioned_sidebars/version-[versionName]-sidebars.json。

  ¥Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as versioned_sidebars/version-[versionName]-sidebars.json.

• 将新版本号附加到 versions.json。

  ¥Append the new version number to versions.json.

创建新文档

¥Creating new docs

1. 将新文件放入对应版本文件夹中。

   ¥Place the new file into the corresponding version folder.

2. 根据版本号将新文件的引用包含在相应的侧边栏文件中。

   ¥Include the reference to the new file in the corresponding sidebar file according to the version number.

Current version structure

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

Older version structure

# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json

提示

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

¥Versioned sidebar files are, like standard sidebar files, relative to the content root for the given version — so for the example above, your versioned sidebar file may look like:

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

或者对于手动侧边栏：

¥or for a manual sidebar:

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

更新现有版本

¥Updating an existing version

你可以同时更新多个文档版本，因为 versioned_docs/ 中的每个目录在发布时都代表特定的路由。

¥You can update multiple docs versions at the same time because each directory in versioned_docs/ represents specific routes when published.

1. 编辑任何文件。

   ¥Edit any file.

2. 提交并推送更改。

   ¥Commit and push changes.

3. 它将发布到版本中。

   ¥It will be published to the version.

示例：当你更改 versioned_docs/version-2.6/ 中的任何文件时，它只会影响版本 2.6 的文档。

¥Example: When you change any file in versioned_docs/version-2.6/, it will only affect the docs for version 2.6.

删除现有版本

¥Deleting an existing version

你也可以删除/删除版本。

¥You can delete/remove versions as well.

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

   ¥Remove the version from versions.json.

示例：

¥Example:

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

2. 删除版本化的文档目录。示例：versioned_docs/version-1.8.0。

   ¥Delete the versioned docs directory. Example: versioned_docs/version-1.8.0.

3. 删除版本控制的侧边栏文件。示例：versioned_sidebars/version-1.8.0-sidebars.json。

   ¥Delete the versioned sidebars file. Example: versioned_sidebars/version-1.8.0-sidebars.json.

配置版本控制行为

¥Configuring versioning behavior

"current" 版本是 ./docs 文件夹的版本名称。管理版本控制的方法有多种，但两种非常常见的模式是：

¥The "current" version is the version name for the ./docs folder. There are different ways to manage versioning, but two very common patterns are:

• 你发布了 v1，并立即开始处理 v2（包括其文档）。本例中当前版本为 v2，位于 ./docs 源文件夹中，可以在 example.com/docs/next 处浏览。最新版本是 v1，位于 ./versioned_docs/version-1 源文件夹中，大多数用户在 example.com/docs 时浏览。

  ¥You release v1, and start immediately working on v2 (including its docs). In this case, the current version is v2, which is in the ./docs source folder, and can be browsed at example.com/docs/next. The latest version is v1, which is in the ./versioned_docs/version-1 source folder, and is browsed by most of your users at example.com/docs.

• 你发布了 v1，并在考虑 v2 之前维护它一段时间。在这种情况下，当前版本和最新版本都将指向 v1，因为 v2 文档甚至还不存在！

  ¥You release v1, and will maintain it for some time before thinking about v2. In this case, the current version and latest version will both be point to v1, since the v2 docs doesn't even exist yet!

Docusaurus 默认设置非常适合第一个用例。我们会将当前版本标记为 "next"，你甚至可以选择不发布。

¥Docusaurus defaults work great for the first use case. We will label the current version as "next" and you can even choose not to publish it.

对于第二个用例：如果你发布 v1 并且不打算很快开发 v2，你可以考虑 "pretending" 当前版本是删减版本，而不是对 v1 进行版本控制并必须在 2 个文件夹（./docs + ./versioned_docs/version-1.0.0）中维护文档 路径和标签：

¥For the 2nd use case: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (./docs + ./versioned_docs/version-1.0.0), you may consider "pretending" that the current version is a cut version by giving it a path and a label:

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 文件夹。

¥The docs in ./docs will be served at /docs/1.0.0 instead of /docs/next, and 1.0.0 will become the default version we link to in the navbar dropdown, and you will only need to maintain a single ./docs folder.

我们提供这些插件选项来自定义版本控制行为：

¥We offer these plugin options to customize versioning behavior:

• disableVersioning：即使有版本，也要明确禁用版本控制。这将使该网站仅包含当前版本。

  ¥disableVersioning: Explicitly disable versioning even with versions. This will make the site only include the current version.

• includeCurrentVersion：包括文档的当前版本（./docs 文件夹）。

  ¥includeCurrentVersion: Include the current version (the ./docs folder) of your docs.

  • 提示：如果当前版本正在开发中，尚未准备好发布，请将其关闭。

    ¥Tip: turn it off if the current version is a work-in-progress, not ready to be published.

• lastVersion：设置 "最新版本"（/docs 路由）所指的版本。

  ¥lastVersion: Sets which version "latest version" (the /docs route) refers to.

  • 提示：如果你当前的版本是指不断修补和发布的主要版本，则 lastVersion: 'current' 有意义。最新版本的实际路由基础路径和标签是可配置的。

    ¥Tip: lastVersion: 'current' makes sense if your current version refers to a major version that's constantly patched and released. The actual route base path and label of the latest version are configurable.

• onlyIncludeVersions：定义要部署的 versions.json 版本的子集。

  ¥onlyIncludeVersions: Defines a subset of versions from versions.json to be deployed.

  • 提示：将开发和部署预览中的版本限制为 2 或 3 个，以缩短启动和构建时间。

    ¥Tip: limit to 2 or 3 versions in dev and deploy previews to improve startup and build time.

• versions：版本元数据字典。对于每个版本，你可以自定义以下内容：

  ¥versions: A dictionary of version metadata. For each version, you can customize the following:

  • label：版本下拉列表和横幅中显示的标签。

    ¥label: the label displayed in the versions dropdown and banner.

  • path：该版本的路由基本路径。默认情况下，最新版本为 /，当前版本为 /next。

    ¥path: the route base path of this version. By default, latest version has / and current version has /next.

  • banner：'none'、'unreleased' 和 'unmaintained' 之一。确定每个文档页面顶部显示的内容。高于最新版本的任何版本均为 "unreleased"，低于最新版本的任何版本均为 "unmaintained"。

    ¥banner: one of 'none', 'unreleased', and 'unmaintained'. Determines what's displayed at the top of every doc page. Any version above the latest version would be "unreleased", and any version below would be "unmaintained".

  • badge：在该版本的文档顶部显示带有版本名称的徽章。

    ¥badge: show a badge with the version name at the top of a doc of that version.

  • className：将自定义 className 添加到该版本的文档页面的 <html> 元素。

    ¥className: add a custom className to the <html> element of doc pages of that version.

详细信息请参见 文档插件配置。

¥See docs plugin configuration for more details.

导航栏项目

¥Navbar items

我们提供了多个导航栏项目来帮助你快速设置导航，而不必担心版本化的路由。

¥We offer several navbar items to help you quickly set up navigation without worrying about versioned routes.

• doc：文档的链接。

  ¥doc: a link to a doc.

• docSidebar：侧边栏中第一项的链接。

  ¥docSidebar: a link to the first item in a sidebar.

• docsVersion：当前查看版本的主文档的链接。

  ¥docsVersion: a link to the main doc of the currently viewed version.

• docsVersionDropdown：包含所有可用版本的下拉列表。

  ¥docsVersionDropdown: a dropdown containing all the versions available.

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

¥These links would all look for an appropriate version to link to, in the following order:

1. 活动版本：用户当前正在浏览的版本（如果她位于此文档插件提供的页面上）。如果她不在文档页面上，请返回...

   ¥Active version: the version that the user is currently browsing, if she is on a page provided by this doc plugin. If she's not on a doc page, fall back to...

2. 首选版本：用户上次查看的版本。如果没有历史，就回到...

   ¥Preferred version: the version that the user last viewed. If there's no history, fall back to...

3. 最新版本：我们导航到的默认版本，由 lastVersion 选项配置。

   ¥Latest version: the default version that we navigate to, configured by the lastVersion option.

推荐做法

¥Recommended practices

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

¥Version your documentation only when needed

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

¥For example, you are building documentation for your npm package foo and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.

你是否应该删除新的文档版本 1.0.1？你可能不应该。1.0.1 和 1.0.0 文档不应根据 semver 有所不同，因为没有新功能！。为其剪切新版本只会创建不必要的重复文件。

¥Should you cut a new documentation version 1.0.1? You probably shouldn't. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.

保持较小的版本数量

¥Keep the number of versions small

根据经验，尽量将版本数量保持在 10 以下。你很可能会拥有许多过时的版本化文档，甚至没有人会再阅读。例如，Jest 目前是 27.4 版本，只维护了几个最新的文档版本，最低的是 25.X。保持小 😊

¥As a good rule of thumb, try to keep the number of your versions below 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. Keep it small 😊

存档旧版本

如果你将站点部署在 Jamstack 提供程序（例如 Netlify）上，该提供程序会将每个生产版本保存为不可变 URL 下的快照。你可以包含永远不会重建的存档版本作为这些不可变 URL 的外部链接。Jest 网站和 Docusaurus 网站都使用这种模式来保持较低的活跃构建版本数量。

¥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. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docusaurus website both use such pattern to keep the number of actively built versions low.

在文档中使用绝对导入

¥Use absolute import within the docs

不要在文档中使用相对路径导入。因为当我们剪切版本时，路径不再起作用（嵌套级别不同，以及其他原因）。你可以使用 Docusaurus 提供的 @site 别名来指向 website 目录。示例：

¥Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the @site alias provided by Docusaurus that points to the website directory. Example:

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

按文件路径链接文档

¥Link docs by file paths

通过带有 .md 扩展名的相对文件路径引用其他文档，以便 Docusaurus 在构建过程中将它们重写为实际的 URL 路径。文件将链接到正确的相应版本。

¥Refer to other docs by relative file paths with the .md extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

全局或版本化的并置资源

¥Global or versioned collocated assets

你应该决定图片和文件等资源是按版本分配还是在版本之间共享。

¥You should decide if assets like images and files are per-version or shared between versions.

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

¥If your assets should be versioned, put them in the docs version, and use relative paths:

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



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

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

¥If your assets are global, put them in /static and use absolute paths:

![img alt](/myImage.png)



[download this file](/file.pdf)