进阶 docusaurus.io 2026-10-13 10:58:59 · 22 阅读
第21章 Docusaurus 第21章：文档版本控制指南
Version: 2.x版本控制
你可以使用版本控制 CLI 基于当前 docs 目录中的最新内容创建一个新的文档版本。这样一来，即使 docs 目录中的文档继续演进，这一特定版本的文档也会被保留下来，随时可以访问。
warning在开始对文档做版本控制之前，请三思——这可能会让贡献者难以帮忙改进文档！
大多数情况下你并不需要版本控制，它只会拖慢构建速度，并给代码库增加复杂度。版本控制最适合文档访问量大、且各版本之间文档变动频繁的网站。如果你的文档很少变动，就不要加版本控制。
想进一步了解版本控制的工作原理、判断它是否适合你的需求，可以继续往下读。
概述
一个典型的带版本控制的文档站点结构如下：
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
+ import Foo from '@site/src/components/Foo';
通过文件路径链接文档 使用 .md 扩展名的相对文件路径引用其他文档，以便 Docusaurus 在构建时将它们重写为实际的 URL 路径。文件将链接到对应的正确版本。 [@hello](hello.mdx#paginate) 文档非常出色。
详情请参阅 [教程](../getting-started/tutorial.mdx)。
全局或版本化的资源 你需要决定像图片和文件这类资源是按版本管理还是跨版本共享。 如果资源需要版本化，将其放在 docs 版本目录中，并使用相对路径： 
[下载此文件](./file.pdf)
如果资源是全局的，将其放在 /static 目录中，并使用绝对路径： 
[下载此文件](/file.pdf)
├── 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.md |
1.0.0 | /docs/1.0.0/hello |
versioned_docs/version-1.1.0/hello.md |
1.1.0（最新） | /docs/hello |
docs/hello.md |
当前 | /docs/next/hello |
提示：
docs目录中的文件属于当前文档版本。默认情况下，当前文档版本被标记为 Next，并托管在/docs/next/*下，但你可以完全根据项目的发布周期进行自定义配置。
术语定义
注意我们在这里使用的术语：
- 当前版本（Current version）：放置于
./docs文件夹中的版本。 - 最新版本（Latest version）/ 上一个版本（Last version）：文档导航栏默认指向的版本，通常路径为
/docs。
“当前版本”由文件系统位置定义，而“最新版本”由导航行为定义。两者可能相同，也可能不同！（在上述默认配置中，它们被视为不同：当前版本位于 /docs/next，最新版本位于 /docs。）
教程
标记新版本
- 首先，确保当前文档版本（
./docs目录）已准备就绪，可以被冻结。 - 输入新的版本号。
// 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
// bun
bun run docusaurus docs:version 1.1.0
当标记一个新版本时，文档版本机制将执行以下操作：
- 复制完整的
docs/文件夹内容到新的versioned_docs/version-[versionName]/文件夹中。 - 基于当前的侧边栏配置（如果存在）创建带版本的侧边栏文件，保存为
versioned_sidebars/version-[versionName]-sidebars.json。 - 将新的版本号追加到
versions.json中。
创建新文档
- 将新文件放入对应的版本文件夹中。
- 根据版本号，在对应的侧边栏文件中包含对新文件的引用。
当前版本结构
# 新文件。
docs/new.md
# 编辑对应的侧边栏文件。
sidebars.js
旧版本结构
# 新文件。
versioned_docs/version-1.0.0/new.md
# 编辑对应的侧边栏文件。
versioned_sidebars/version-1.0.0-sidebars.json
+ import Foo from '@site/src/components/Foo';
通过文件路径链接文档 使用 .md 扩展名的相对文件路径引用其他文档，以便 Docusaurus 在构建时将它们重写为实际的 URL 路径。文件将链接到对应的正确版本。 [@hello](hello.mdx#paginate) 文档非常出色。
详情请参阅 [教程](../getting-started/tutorial.mdx)。
全局或版本化的资源 你需要决定像图片和文件这类资源是按版本管理还是跨版本共享。 如果资源需要版本化，将其放在 docs 版本目录中，并使用相对路径： 
[下载此文件](./file.pdf)
如果资源是全局的，将其放在 /static 目录中，并使用绝对路径： 
[下载此文件](/file.pdf)
