跳到主要内容
版本：3.2.1

分版

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.

warning

在给你的文档划分版本之前，请三思——贡献者可能会更难帮助改进文档！

大多数情况下，你不需要划分文档版本，这样不仅会延长构建时间，还会把你的代码复杂化。 Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. 如果你的文档很少更改，请不要给你的文档划分版本。

为了深入了解版本化是怎么工作的，并查看它是否符合你的需要，你可以继续阅读下文。

Overview​

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

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

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

下表解释了版本化的文件是如何从版本映射到生成的 URL 的。

路径版本URL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0（最新）/docs/hello
docs/hello.mdcurrent/docs/next/hello
提示

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

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​

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

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.

Current version is defined by the file system location, while latest version is defined by the the navigation behavior. 它们可能是同一个版本，也可能不是同一个版本！ (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. First, make sure the current docs version (the ./docs directory) is ready to be frozen.
  2. 输入新的版本号。
npm run docusaurus docs:version 1.1.0

标记新版本时，文档分版机制会：

  • Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder.
  • Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as versioned_sidebars/version-[versionName]-sidebars.json.
  • Append the new version number to versions.json.

Creating new docs​

  1. 把新文件放在相应版本的文件夹中。
  2. 根据版本号，在相应的侧边栏文件中添加新文件的引用。
# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js
提示

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​

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

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

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​

你也可以删除版本。

  1. Remove the version from versions.json.

示例：

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]
  1. 删除版本化文档目录。 Example: versioned_docs/version-1.8.0.
  2. 删除版本化侧边栏文件。 Example: versioned_sidebars/version-1.8.0-sidebars.json.

Configuring versioning behavior​

The "current" version is the version name for the ./docs folder. 版本管理的方式有很多种，但有两个非常常见的模式：

  • 你发布了 v1，然后立刻开始着手于 v2（包括其文档）。 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。 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)，你甚至可以选择不发布它。

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',
        },
      },
    },
  ],
};

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.

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

  • disableVersioning: Explicitly disable versioning even with versions. 这会让网站只包含当前版本。
  • 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: Sets which version "latest version" (the /docs route) refers to.
    • Tip: lastVersion: 'current' makes sense if your current version refers to a major version that's constantly patched and released. 最新版本的实际 URL 路径前缀和标签都是可以设置的。
  • onlyIncludeVersions: Defines a subset of versions from versions.json to be deployed.
    • Tip: limit to 2 or 3 versions in dev and deploy previews to improve startup and build time.
  • versions: A dictionary of version metadata. 对于每个版本，你可以自定义以下内容：
    • label: the label displayed in the versions dropdown and banner.
    • path: the route base path of this version. By default, latest version has / and current version has /next.
    • banner: one of 'none', 'unreleased', and 'unmaintained'. 决定每个文档页面的顶部显示什么横幅。 所有在最新版本之后的版本都是「未发布」("unreleased")，而在最新版本之前的版本都是「停止维护」("unmaintained")。
    • badge: show a badge with the version name at the top of a doc of that version.
    • className: add a custom className to the <html> element of doc pages of that version.

See docs plugin configuration for more details.

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

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

  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.

Version your documentation only when needed​

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 版本文档吗？ You probably shouldn't. 按照语义化版本规范，1.0.1 和 1.0.0 的文档不应该有区别，因为没有新功能！ 这时候划分新版本只会创造不必要的重复文件。

Keep the number of versions small​

一个好用的经验法则是，把版本数量保持在 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 网站都使用这种模式，保持有限的活跃构建版本数量。

Use absolute import within the docs​

不要在文档中使用相对路径导入。 因为当我们划分版本后，这些路径就不再起作用了（因为文件夹嵌套层级不一样了，等等）。 You can utilize the @site alias provided by Docusaurus that points to the website directory. 示例：

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

Global or versioned collocated assets​

你需要决定像图像和文件这样的资源是每个版本专有的，还是在版本之间共享。

如果你的资源是和版本相关的，把它们放在版本文件夹中，并使用相对路径：

![图片 alt](./myImage.png)

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

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

![图片 alt](/myImage.png)

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