跳到主要内容

版本控制

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

注意

在开始对文档进行版本控制之前要仔细考虑 - 这可能会使贡献者难以帮助改进文档！

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

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

概述​

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

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

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/next/hello
提示

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

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

术语​

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

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

当前版本由文件系统位置定义，而最新版本由导航行为定义。它们可能是也可能不是同一个版本！（并且默认配置如上表所示，会将它们视为不同的版本：当前版本在 /docs/next，最新版本在 /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. 根据版本号在相应的侧边栏文件中包含新文件的引用。
# 新文件
docs/new.md

# 编辑相应的侧边栏文件
sidebars.js
提示

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

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

或对于手动侧边栏：

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

更新现有版本​

您可以同时更新多个文档版本，因为 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。

配置版本控制行为​

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

  • 您发布 v1，并立即开始工作 v2（包括其文档）。在这种情况下，current version 是 v2，它位于 ./docs 源文件夹中，可以在 example.com/docs/next 下浏览。latest version 是 v1，它位于 ./versioned_docs/version-1 源文件夹中，并由大多数用户在 example.com/docs 下浏览。
  • 您发布 v1，并将在一段时间内维护它，然后再考虑 v2。在这种情况下，current version 和 latest version 都将指向 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 文件夹）的文档。
    • Tip: 如果当前版本是正在进行的工作，尚未准备好发布，请关闭它。
  • lastVersion: 设置哪个版本 "latest version"（/docs 路由）指的是。
    • Tip: lastVersion: 'current' 对于您的当前版本是指向主要版本，该版本不断被修补和发布的情况很有意义。实际路由路径和标签的最新版本是可配置的。
  • onlyIncludeVersions: 定义从 versions.json 中部署的版本子集。
    • Tip: 在 dev 和部署预览中限制为 2 或 3 个版本，以提高启动和构建时间。
  • versions: 版本元数据的字典。对于每个版本，您可以自定义以下内容：
    • label: 版本下拉菜单和横幅中显示的标签。
    • path: 此版本的路线基本路径。默认情况下，最新版本有 /，当前版本有 /next。
    • banner: 一个 'none', 'unreleased', 和 'unmaintained'。确定每个版本页面的顶部显示的内容。任何高于最新版本的版本都将被视为 "unreleased"，任何低于最新版本的版本都将被视为 "unmaintained"。
    • badge: 在版本页面的顶部显示版本名称的徽章。
    • className: 向该版本的文档页面添加自定义 className。

请参阅 docs 插件配置 了解更多详细信息。

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

这些链接将查找适当的版本以链接，按以下顺序：

  1. Active version: 如果用户当前正在浏览页面，则为用户当前浏览的版本。如果她不在文档页面上，则回退到...
  2. Preferred version: 用户上次查看的版本。如果没有任何历史记录，则回退到...
  3. Latest version: 默认版本，由 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 文档不应该根据 semver 进行差异，因为没有任何新功能！为它创建一个新的版本只会创建不必要的重复文件。

保持版本数量少​

作为一条很好的经验法则，尝试将您的版本数量保持在 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)