Docusaurus 2 文档多版本管理实战：从版本发布、导航栏切换到增量更新

Docusaurus 2 文档多版本管理实战：从版本发布、导航栏切换到增量更新

【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples

导读

Docusaurus 2 内置了开箱即用的**文档版本管理（Docs Versioning）**能力，让你可以在同一站点上同时维护“已发布版本”与“即将发布（unreleased）版本”两套文档，并通过导航栏下拉菜单让读者一键切换。本文基于仓库中的 Docusaurus 2 模板（framework-boilerplates/docusaurus-2）及其文档 manage-docs-versions.md，完整讲解版本创建、URL 路由规则、导航栏版本下拉菜单配置，以及版本快照后的增量更新流程。读完本文，你将能独立为一个 Docusaurus 2 文档站建立多版本体系，并理解其底层目录结构与配置机制。

版本管理机制概述

Docusaurus 可以同时管理文档的多个版本，其核心思想是：以docs目录为"当前开发版本"（current），发布时把整份文档目录快照（snapshot）拷贝到独立的versioned_docs目录，之后该版本的内容与开发中的文档互不干扰。

在仓库的 Docusaurus 2 模板中，文档源码的组织方式如下（路径以仓库根目录为基准）：

• docs/tutorial-basics：基础教程文档，如创建页面、文档、博客文章、部署站点等；
• docs/tutorial-extras：进阶主题，包括本文讲解的版本管理（manage-docs-versions.md）与站点翻译（translate-your-site.md）；
• docs/intro.md：站点介绍入口。

侧边栏由 sidebars.js 定义，模板默认使用{type: 'autogenerated', dirName: '.'}从docs目录结构自动生成，因此新增版本后，只要目录结构一致，侧边栏会自动同步：

// sidebars.js const sidebars = { tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], }; module.exports = sidebars;

创建文档版本（Release a Version）

执行版本发布命令

当你的项目准备发布 1.0 版本时，在项目根目录执行（仓库模板的 package.json 已内置docusaurus脚本，npm run docusaurus等价于直接调用 CLI）：

npm run docusaurus docs:version 1.0

该命令执行后，Docusaurus 会完成两件事：

1. 将docs文件夹完整复制到versioned_docs/version-1.0，形成 1.0 版本的文档快照；
2. 在项目根目录生成versions.json文件，记录所有已发布版本的列表（例如["1.0"]），该文件同时驱动版本下拉菜单的选项渲染。

docs:version命令接受一个版本号字符串作为唯一位置参数，版本号会同时用于目录命名（version-1.0）与 URL 路径（/docs/）。如果你要发布其他版本，如2.0、1.5，直接替换参数即可，例如：

npm run docusaurus docs:version 2.0

发布后的目录结构与 URL 路由

发布 1.0 版本后，你的文档站同时拥有两个版本：

也就是说：

• 已发布的 1.0 版本是默认版本，直接挂在/docs/路径下；
• 正在开发中的文档被标记为current，路由到带next前缀的/docs/next/，向读者明确传达"这是即将发布、内容可能变化的文档"。

这一路由约定是 Docusaurus 版本管理的核心约定：next前缀专门用于未发布文档，避免读者误把开发中的内容当作稳定版。模板中所有文档文件的相对链接（如文档之间互相引用）在版本化后依旧有效，因为快照保留了完整的目录结构。

在导航栏添加版本下拉菜单

为了让读者在不同版本间无缝切换，Docusaurus 提供了docsVersionDropdown导航项。修改项目根目录的 docusaurus.config.js，在themeConfig.navbar.items数组中追加该配置项：

module.exports = { themeConfig: { navbar: { items: [ // highlight-start { type: 'docsVersionDropdown', }, // highlight-end ], }, }, };

在仓库模板现有的 docusaurus.config.js 中，navbar.items已包含Tutorial（type: 'doc'）、Blog、GitHub等条目，你只需把上述docsVersionDropdown对象按需插入（通常放在文档类导航项附近），保存后重启开发服务器：

npm run start

导航栏即会出现版本下拉菜单，效果如仓库中的截图所示：

从截图可以看到，下拉菜单默认把next（未发布版本）与1.0（已发布版本）并列展示，当前所在版本高亮显示，页面内容区同时会显示 "Version: 1.0" 之类的版本标识，帮助读者确认正在阅读的文档版本。

与版本下拉菜单同族的还有localeDropdown（语言下拉菜单），用于多语言站点的切换，见 translate-your-site.md。两者的配置位置与方式完全一致，可以同时存在。

更新已发布的版本

版本发布后，docs/与versioned_docs/version-1.0/成为两份相互独立的文档副本，修改任何一方都不会影响另一方。这带来两条明确的更新路径：

• 编辑versioned_docs/version-1.0/hello.md，会更新线上 1.0 版本页面http://localhost:3000/docs/hello；
• 编辑docs/hello.md，会更新开发中版本页面http://localhost:3000/docs/next/hello。

这一机制的意义在于：修复已发布版本的文档错误时，只改快照目录，不会把仍在编写中的新内容提前暴露给稳定版读者；而日常新增、改写文档则统一在docs/目录进行，等到下次发布新版本（再次执行docs:version）时，再整体生成新的快照。

从模板的文档组织可以看到，版本化后的文档同样支持完整的 Docusaurus 文档特性：front matter 元数据（sidebar_position、sidebar_label）、侧边栏自动生成、文档间相对链接等，参见 create-a-document.md 中对文档 front matter 与侧边栏配置的说明——这些能力在versioned_docs目录下同样生效，因为版本快照本质上就是一份结构相同的 Markdown 文档集。

本地验证与运行方式

仓库中的 Docusaurus 2 模板（framework-boilerplates/docusaurus-2）是一个可在 Vercel 零配置部署的示例站点，依赖锁定在 package.json 中（@docusaurus/core与@docusaurus/preset-classic均为2.0.1）。要本地验证本文的所有操作，可以按以下步骤：

# 1. 安装依赖（仓库根目录或该模板目录下，取决于你的包管理器） npm install # 2. 启动本地开发服务器 npm run start # 3. 发布一个文档版本 npm run docusaurus docs:version 1.0 # 4. 为生产环境构建静态站点 npm run build

构建产物会按版本生成对应的静态页面，versions.json与versioned_docs目录都应纳入版本控制，以保证团队成员与 CI 环境拿到一致的版本列表。若需要重新生成文档标题锚点 ID，还可以使用npm run docusaurus write-heading-ids（该脚本同样已定义在模板的 package.json 中）。

小结

Docusaurus 2 的多版本管理可以用三句话概括：docs:version命令一键快照当前文档并生成版本清单；docs与versioned_docs双目录支撑"开发中"与"已发布"两套独立内容；docsVersionDropdown一行配置让读者在导航栏自由切换版本。这套机制特别适合需要"稳定文档 + 持续演进"并行的项目，值得作为文档站点建设的基础设施直接采用。

【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples