跳到主要内容
版本：3.8.1

版本控制

您可以使用版本控制 CLI 根据 docs 目录中的最新内容创建新的文档版本。即使 docs 目录中的文档持续演进，该特定文档集也将被保留并可访问。

警告

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

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

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

概述​

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

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/foo/bar
│   └── hello.md         # https://mysite.com/docs/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。

路径版本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.md当前/docs/hello
提示

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

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

术语​

请注意我们在此处使用的术语。

当前版本
放置在 ./docs 文件夹中的版本。
最新版本 / 默认版本
为文档导航栏项目默认提供的版本。通常路径为 /docs。

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

教程​

标记新版本​

  1. 首先，请确保当前文档版本（./docs 目录）已准备好被冻结。
  2. 输入新的版本号。
npm run docusaurus docs:version 1.1.0

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

  • 将 docs/ 文件夹的全部内容复制到一个新的 versioned_docs/version-[versionName]/ 文件夹中。
  • 根据您当前的 侧边栏 配置（如果存在）创建一个版本化的侧边栏文件——保存为 versioned_sidebars/version-[versionName]-sidebars.json。
  • 将新的版本号追加到 versions.json 中。

创建新文档​

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

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

版本化的侧边栏文件，与标准侧边栏文件一样，是相对于给定版本的内容根目录的——因此对于上述示例，您的版本化侧边栏文件可能看起来像

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

或者对于手动侧边栏

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

更新现有版本​

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

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

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

删除现有版本​

您也可以删除/移除版本。

  1. 从 versions.json 中移除该版本。

示例

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

配置版本控制行为​

“当前”版本是 ./docs 文件夹的版本名称。管理版本控制有不同的方式，但两种非常常见的模式是

  • 您发布了 v1，并立即开始开发 v2（包括其文档）。在这种情况下，当前版本是 v2，位于 ./docs 源文件夹中，可以通过 example.com/docs 浏览。最新版本是 v1，位于 ./versioned_docs/version-1 源文件夹中，大多数用户通过 example.com/docs 浏览。
  • 您发布了 v1，并将在考虑 v2 之前维护一段时间。在这种情况下，当前版本和最新版本都将指向 v1，因为 v2 文档甚至还不存在！

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

对于第二种用例：如果您发布 v1 并且不打算很快开发 v2，那么与其对 v1 进行版本控制并不得不在 2 个文件夹（./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，并且 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：为该版本文档页面的 <html> 元素添加自定义 className。

有关更多详细信息，请参阅 文档插件配置。

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

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

这些链接都将按以下顺序查找合适的版本进行链接

  1. 活动版本：如果用户正在此文档插件提供的页面上，则为用户当前正在浏览的版本。如果她不在文档页面上，则回退到...
  2. 首选版本：用户上次查看的版本。如果没有历史记录，则回退到...
  3. 最新版本：我们导航到的默认版本，由 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: 'Version 4.0'},
            '3.0': {label: 'Version 3.0'},
            '2.0': {label: 'Version 2.0'},
          },
        },
      ],
    },
  },
};

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

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

您应该发布一个新的文档版本 1.0.1 吗？您可能不应该。根据语义化版本控制，1.0.1 和 1.0.0 的文档不应该有区别，因为没有新功能！为此发布新版本只会创建不必要的重复文件。

保持版本数量少​

作为一条经验法则，尽量将您的版本数量保持在 10 个以下。您很可能会有大量过时的版本化文档，根本没有人再阅读。例如，Jest 当前版本为 27.4，并且只维护几个最新的文档版本，最低版本为 25.X。保持小巧 😊

归档旧版本

如果您在 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)