rock-docs

name	rock-docs
description	为 ROCK 项目管理 Docusaurus 文档版本。支持添加新版本文档、添加 Release Note、管理中英文 i18n 文档。当用户说"添加文档版本"、"发布新版本文档"、"添加 release note"、"rock-docs"或需要操作 docs/ 目录下的版本化文档时使用。 Use when this capability is needed.
metadata	{"author":"alibaba"}

ROCK Docs

管理 ROCK 项目的 Docusaurus 版本化文档。

项目背景

• Docusaurus 3.9.x，部署于 https://alibaba.github.io/ROCK/
• 语言：英文（默认）+ 中文（zh-Hans）
• includeCurrentVersion: false，所有发布内容来自 versioned_docs/
• versions.json 驱动版本注册，convertVersionsArrayToObject() 自动生成配置
• 侧边栏：顶层手动 + 内层 autogenerated
• Release Notes 通过 reverseReleaseNoteSidebars() 自动倒序排列

需要操作的 6 个位置

#	操作	路径
1	创建英文文档目录	docs/versioned_docs/version-{NEW}/
2	创建版本侧边栏	docs/versioned_sidebars/version-{NEW}-sidebars.json
3	更新版本列表	docs/versions.json
4	更新最新版本指向	docs/docusaurus.config.js 中的 lastVersion
5	创建中文文档目录	docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/
6	创建中文侧边栏翻译	docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json

标准目录结构

version-X.Y.x/
├── Getting Started/
├── User Guides/
├── References/
│   ├── api.md
│   └── Python SDK References/
├── Release Notes/
│   ├── index.md
│   └── vX.Y.Z.md
└── overview.md

执行流程

Phase 0：版本冲突检测

1. 读取 docs/versions.json 获取已有版本列表
2. 从用户输入的版本号推断文档版本号（如 1.4.5 → 1.4.x）
3. 如果文档版本已存在，跳转至「仅添加 Release Note」流程

仅添加 Release Note 流程

Step A：创建英文 Release Note

• 路径：docs/versioned_docs/version-{EXISTING}/Release Notes/v{VERSION}.md
• 使用下方英文模板

Step B：创建中文 Release Note

• 路径：docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{EXISTING}/Release Notes/v{VERSION}.md
• 使用下方中文模板

Step C：更新 Release Notes 索引

在英文和中文 Release Notes/index.md 的标题行下方第一行插入：

* [release v{VERSION}](v{VERSION}.md)

完成后跳转至 Phase 5 验证。

---

如果文档版本不存在，继续执行完整流程。

Phase 1：收集信息

1. 新版本号：如 1.4.x

2. 基础版本：从哪个版本复制？默认取 versions.json 第一项

3. Release Note：是否创建？版本号是什么？

4. 是否修改 lastVersion：必须明确告知用户影响后再确认：

   ⚠️ 修改 lastVersion 会改变文档站点默认展示版本。当前为 {当前 lastVersion}，修改后为 {NEW}。是否确认？

   不要默认选「是」，等用户明确确认。

具体版本号（如 1.4.0）自动推断为文档版本号（1.4.x）。

Phase 2：创建英文文档

Step 1：复制英文文档目录

cp -r docs/versioned_docs/version-{BASE}/ docs/versioned_docs/version-{NEW}/

Step 1.5：清理旧版本 Release Notes（仅主版本号变更时）

当主版本号（major.minor）不同时（如 1.4.x → 1.5.x）：

1. 删除 docs/versioned_docs/version-{NEW}/Release Notes/ 下除 index.md 外的所有 v*.md
2. 重写 index.md：

---
sidebar_position: 1
---
# Release Notes

Step 2：复制版本侧边栏

cp docs/versioned_sidebars/version-{BASE}-sidebars.json docs/versioned_sidebars/version-{NEW}-sidebars.json

Step 3：创建 Release Note（如果需要）

英文模板 docs/versioned_docs/version-{NEW}/Release Notes/v{VERSION}.md：

# v{VERSION}

## Release Date
{Mon DD, YYYY}

---

TODO

中文模板 docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/v{VERSION}.md：

# v{VERSION}

## 发布日期
{YYYY} 年 {M} 月 {D} 日

---

TODO

Step 3.5：更新 Release Notes 索引

在英文 docs/versioned_docs/version-{NEW}/Release Notes/index.md 标题行下方第一行插入：

* [release v{VERSION}](v{VERSION}.md)

Phase 3：创建中文文档

Step 4：复制中文文档目录

cp -r docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}/ docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/

Step 4.5：清理中文旧版本 Release Notes（仅主版本号变更时）

与 Step 1.5 同理：

1. 删除 docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/ 下除 index.md 外的所有 v*.md
2. 重写 index.md（中文版标题为 # 版本说明）：

---
sidebar_position: 1
---
# 版本说明

Step 5：创建中文侧边栏翻译 JSON

cp docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}.json docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json

修改新 JSON 文件中的 version.label：

{
  "version.label": {
    "message": "{NEW}",
    "description": "The label for version {NEW}"
  }
}

Phase 4：更新配置

Step 6：更新 versions.json

在 docs/versions.json 数组开头插入 {NEW}。

Step 7：更新 docusaurus.config.js（仅用户明确确认后）

修改 docs/docusaurus.config.js 中的 lastVersion 从 {BASE} 为 {NEW}。用户选择不修改则跳过。

Phase 5：验证

Step 8：构建验证

cd docs && npm run build

构建成功后启动预览：

cd docs && npm run serve

npm run serve 基于构建产物启动，支持中英文切换验证。npm run start 仅加载默认语言，无法验证中文。

Step 9：手动检查清单

✅ 文档验证清单：

英文版本检查：
   □ 版本下拉菜单中是否显示新版本
   □ 默认展示版本是否符合预期
   □ 英文文档页面是否正常渲染
   □ Release Notes 是否按版本号倒序排列
   □ 侧边栏导航是否完整

中文版本检查（右上角语言切换）：
   □ 中文文档页面是否正常显示
   □ 侧边栏分类名称是否正确翻译
   □ Release Notes 内容是否与英文版本对应

后续工作：
   □ 更新新版本英文文档中的具体内容
   □ 更新中文文档翻译内容
   □ 如有 Release Note，补充具体发布内容

注意事项

• docs/rock/ 是未发布版本源码，includeCurrentVersion: false 不会发布
• HiddenSidebars 中的文件会从侧边栏隐藏，但仍可通过直接链接访问
• 详细 i18n 配置、侧边栏管理、翻译流程参见 references/i18n-guide.md

---

Source: alibaba/ROCK — distributed by TomeVault.