跳到主要内容

3、版本控制

该文档创建于2024-09-04，最后更新于2024-09-03。

版本控制​

你可以使用版本控制 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/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 文件是版本名称列表，按从最新到最旧的顺序排列。

下表说明了版本控制文件如何映射到其版本和生成的 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

提示

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

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

术语​

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

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

教程​

标记新版本​

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

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

  • 将完整的 docs/ 文件夹内容复制到新的 versioned_docs/version-[versionName]/ 文件夹中。
  • 根据当前 sidebar 配置创建版本化侧边栏文件（如果存在） - 另存为 versioned_sidebars/version-[versionName]-sidebars.json。
  • 将新版本号附加到 versions.json。

创建新文档​

  1. 将新文件放入对应版本文件夹中。
  2. 根据版本号将新文件的引用包含在相应的侧边栏文件中。
  • Current version structure
  • Older version structure
# 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。

配置版本控制行为​

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

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

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

对于第二个用例：如果你发布 v1 并且不打算很快开发 v2，你可以考虑 "pretending" 当前版本是删减版本，而不是对 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/next 提供，1.0.0 将成为我们在导航栏下拉列表中链接到的默认版本，你只需要维护一个 ./docs 文件夹。

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

  • disableVersioning：即使有版本，也要明确禁用版本控制。这将使该网站仅包含当前版本。
  • includeCurrentVersion：包括文档的当前版本（./docs 文件夹）。
    • 提示：如果当前版本正在开发中，尚未准备好发布，请将其关闭。
  • lastVersion：设置 "最新版本"（/docs 路由）所指的版本。
    • 提示：如果你当前的版本是指不断修补和发布的主要版本，则 lastVersion: 'current' 有意义。最新版本的实际路由基础路径和标签是可配置的。
  • onlyIncludeVersions：定义要部署的 versions.json 版本的子集。
    • 提示：将开发和部署预览中的版本限制为 2 或 3 个，以缩短启动和构建时间。
  • versions：版本元数据字典。对于每个版本，你可以自定义以下内容：
    • label：版本下拉列表和横幅中显示的标签。
    • path：该版本的路由基本路径。默认情况下，最新版本为 /，当前版本为 /next。
    • banner：'none'、'unreleased' 和 'unmaintained' 之一。确定每个文档页面顶部显示的内容。高于最新版本的任何版本均为 "unreleased"，低于最新版本的任何版本均为 "unmaintained"。
    • badge：在该版本的文档顶部显示带有版本名称的徽章。
    • className：将自定义 className 添加到该版本的文档页面的 <html> 元素。

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

导航栏项目​

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

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

  1. 活动版本：用户当前正在浏览的版本（如果她位于此文档插件提供的页面上）。如果她不在文档页面上，请返回...
  2. 首选版本：用户上次查看的版本。如果没有历史，就回到...
  3. 最新版本：我们导航到的默认版本，由 lastVersion 选项配置。

推荐做法​

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

例如，你正在为 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)
最后由 One 于 更新
0%