版本控制

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.

概述

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

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

The table below explains how a versioned file maps to its version and the generated 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

提示

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.

术语

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.

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

教程

标记新版本

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

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

创建新文档

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

更新现有版本

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.

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

删除现有版本

You can delete/remove versions as well.

1. Remove the version from versions.json.

例子:

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

2. Delete the versioned docs directory. Example: versioned_docs/version-1.8.0.
3. Delete the versioned sidebars file. Example: versioned_sidebars/version-1.8.0-sidebars.json.

配置版本控制行为

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

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

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

module.exports = {
  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.

We offer these plugin options to customize versioning behavior:

• disableVersioning: Explicitly disable versioning even with versions. This will make the site only include the current version.
• 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. The actual route base path and label of the latest version are configurable.
• 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. For each version, you can customize the following:
  • 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'. 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: 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.

导航条项目

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

• doc: a link to a doc.
• docSidebar: a link to the first item in a sidebar.
• docsVersion: a link to the main doc of the currently viewed version.
• 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. Latest version: the default version that we navigate to, configured by the lastVersion option.

建议实践

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

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.

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.

尽量减少版本的数量

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 😊

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

在文档中使用绝对导入

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';

通过文件路径链接文档

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

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

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

全局或版本化的并置资产

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

如果你的资源需要版本化，把它们放在 docs 版本中，并使用相对路径:

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

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

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

![img alt](/myImage.png)

[download this file](/file.pdf)