GitBook 维护指南 (AI Context)

本文档旨在指导 AI 助手和开发者如何维护 docs/GitBook 目录下的文档项目。本项目使用 GitBook 构建 Aegis 框架的使用手册。

1. 目录结构说明

docs/GitBook 是文档项目的根目录，核心结构如下：

• book.json: GitBook 的核心配置文件，定义了插件（plugins）、样式（styles）和元数据。
• SUMMARY.md: 文档的目录结构文件（左侧导航栏）。所有新文档必须在此注册才能显示。
• README.md: 文档的首页（Introduction）。
• content/: 存放具体的 Markdown 文档内容，按模块分类（如 基础文档/, 主要组件/, 其他/）。
• assets/: 存放图片等静态资源。
• styles/: 自定义 CSS 样式（如 website.css）。
• _book/: (Ignored) 构建生成的静态网站目录，不要编辑此目录下的文件。

2. 文档维护流程

2.1 添加新文档

1. 创建文件: 在 content/ 下的合适子目录中创建 .md 文件。
   • 例如：content/基础文档/新功能.md
2. 编写内容: 使用标准 Markdown 语法编写。
   • 图片引用：将图片放入 assets/，使用相对路径引用，如 ![说明](/assets/image.png)。
3. 注册目录: 打开 SUMMARY.md，在合适的位置添加链接。
   • 格式：* [显示标题](content/基础文档/新功能.md)
   • 注意缩进：使用 Tab 或 4 个空格表示层级关系。

2.2 修改现有文档

• 直接编辑对应的 .md 文件。
• 如果修改了文件名或移动了位置，必须同步更新 SUMMARY.md 中的链接。

2.3 图片资源

• 所有图片应存放在 assets/ 目录下。
• 引用路径: 建议使用相对路径。
  • 在 content/xxx/doc.md 中引用 assets/img.png -> /assets/img.png
  • 在根目录 README.md 中引用 -> /assets/img.png

3. 配置文件 (book.json)

• 通常不需要修改。
• 如果需要启用新插件，在 plugins 数组中添加（注意 GitBook 插件通常需要 npm install，但在纯文本维护模式下，只需确保配置正确）。
• 当前启用的主要插件：search-plus (搜索), anchor-navigation-ex (右侧目录), prism (代码高亮), mermaid-gb3 (图表)。

4. AI 助手操作准则

当用户请求修改或添加文档时：

1. 定位: 首先确认用户指的是哪个章节或文件。
2. 检查: 总是先读取 SUMMARY.md 以了解当前的目录结构。
3. 一致性: 保持 Markdown 风格一致（标题层级、代码块格式）。
4. 完整性: 创建新文件后，永远不要忘记更新 SUMMARY.md。
5. 路径: 引用链接和图片时，仔细计算相对路径层级。
6. 隐身规则: AI_Context.md (本文档) 仅供 AI 和维护者参考，不需要添加到 SUMMARY.md 中，不需要在最终生成的网站中显示。

5. 常用命令 (参考)

虽然主要通过编辑文件维护，但在本地预览时可使用：

• gitbook install: 安装插件
• gitbook serve: 启动本地预览服务器 (http://localhost:4000)
• gitbook build: 生成静态网站到 _book/

6. 版本对比与文档链接

6.1 核心原则

本项目使用的是 Legacy GitBook (v3.x / gitbook-cli)，严禁参考 Modern GitBook (Cloud/SaaS) 的官方文档进行开发，以免产生配置混淆。

6.2 推荐参考文档

由于 Legacy GitBook 官网已不再维护旧版文档，请优先参考以下社区维护的 Legacy 版本文档或本地部署指南：

• GitBook 简明教程 (Legacy): http://www.chengweiyang.cn/gitbook/
  • 中文社区维护的 v3.x 版本教程，涵盖安装、命令、配置和插件。
• GitBook Toolchain Documentation: https://github.com/GitbookIO/gitbook
  • GitHub 仓库中的 README 和文档，最原始的参考。

警告: 请忽略 https://gitbook.com/docs 和 https://docs.gitbook.com，这些均是现代云平台版本的文档，其配置格式 (.gitbook.yaml)、CLI 工具 (@gitbook/cli) 和集成方式与本项目完全不兼容。

6.3 关键差异速查 (Legacy vs Modern)

特性	本项目 (Legacy GitBook)	现代 GitBook (Modern / Cloud)	AI 操作指南
CLI 工具	gitbook-cli (npm package)	@gitbook/cli (npm package)	严禁混淆。本项目使用 gitbook build/serve，绝不要运行 gitbook new/publish。
配置文件	book.json	.gitbook.yaml / UI 配置	必须维护 book.json，忽略 .gitbook.yaml 相关说明。
插件机制	npm packages (e.g. gitbook-plugin-search-plus)	Integrations (Marketplace)	仅使用 npm 插件生态，勿尝试安装云平台集成。

| 目录结构 | 依赖 SUMMARY.md 定义导航 | 自动推断或 UI 管理 | 必须手动维护 SUMMARY.md。 | | 渲染引擎 | 本地 Node.js 生成静态 HTML | 云端动态渲染 | 本地预览需使用 gitbook serve。 | | Markdown | 标准 MD + 插件扩展 (如 {% mermaid %}) | MDX / Block-based content | 保持使用 Legacy 插件语法（如 Mermaid 插件语法）。 |

关键提醒: 现代 GitBook 的 "Integrations" 是指开发第三方应用（如 Slack 连接器），而本项目的 "Plugins" 是指静态网站生成时的功能扩展。两者概念完全不同，请勿参考 Developer Integrations 文档进行开发。

7. 本地部署与构建

Legacy GitBook 的一大优势是可以生成纯静态 HTML 文件，支持完全的本地部署。

7.1 环境准备

• Node.js: 推荐使用 v12.x 或 v14.x。
  • 注意: Node.js v16+ 可能会导致 graceful-fs 报错 (TypeError: cb.apply is not a function)。建议使用 nvm 切换版本。
• GitBook CLI: 全局安装命令行工具。

  npm install gitbook-cli -g

7.2 构建步骤

1. 安装插件: 首次运行或修改 book.json 后需要执行。

   gitbook install

2. 生成静态站:

   gitbook build

   执行成功后，会在根目录下生成 _book/ 文件夹。

7.3 部署

_book/ 目录包含完整的静态网站资源（HTML, CSS, JS, Images）。你可以将其部署到任何静态文件服务器：

• Nginx: 配置 root 指向 _book/ 目录。
• Apache/IIS: 直接拷贝内容到站点根目录。
• GitHub Pages: 将 _book 内容推送到 gh-pages 分支。
• 本地预览:

  gitbook serve

  访问 http://localhost:4000。

8. 常见问题 (FAQ)

8.1 是否支持多版本切换？

Legacy GitBook (v3.x) 原生不支持多版本文档管理。 如果需要实现 v1.0, v2.0 的切换，通常采用以下“多重构建”方案：

1. 独立构建: 为每个版本维护独立的分支或目录，分别执行 gitbook build。
2. 目录部署: 将生成的静态文件部署到子目录（如 docs/v1/, docs/v2/）。
3. UI 插件: 使用插件（如 gitbook-plugin-versions）在右上角添加版本下拉框，或者手动修改 HTML 模板注入跳转脚本。

8.2 是否支持多语言？

支持。 通过在根目录创建 LANGS.md 文件定义语言列表，GitBook 会自动生成多语言入口页。

9. 替代方案推荐 (支持多版本 & 本地部署)

如果未来需要更完善的多版本管理 (Versioning) 且必须本地部署 (Static HTML)，建议迁移至以下现代文档框架：

框架	技术栈	多版本支持	优点	缺点
Docusaurus	React / Node.js	原生支持 (一键归档版本)	Facebook 出品，生态极佳，支持 React 组件，不仅是文档更是网站。	配置相对复杂，对非前端开发者有一定门槛。
MkDocs + Material	Python	通过插件支持 (使用 mike 工具)	配置极其简单 (mkdocs.yml)，主题美观，专注文档。	需 Python 环境，扩展功能不如 React 生态灵活。
VitePress	Vue / Node.js	需手动管理 (目录区分)	极致性能，Vue 驱动。	原生不带版本管理，需自行设计目录结构。

迁移建议: 如果当前 GitBook 遇到瓶颈，优先推荐 Docusaurus (功能最全) 或 MkDocs Material (最易上手)。