Handbook 写作规范
本规范用于统一本仓库 handbook/ 及各模块入口页的写作与排版风格。
语言
- 全中文：标题与说明尽量使用中文。
- 保留英文：产品名、命令、参数、关键字、文件名等保留英文（例如
kubectl、pg_dump、docker-compose.yml）。
- 链接标题：优先使用中文描述（必要时补充英文原名）。
标题层级
- 每个页面仅有一个一级标题：
# 页面标题
- 正文从二级标题开始：
## / ###
链接
- 站内链接：统一使用相对路径，且相对当前文件位置正确。
- 指向目录时使用尾部
/：[AI](./ai/)
- 指向文件时写到
.md：[链接校验](./check-links.md)
- 外部链接：不要裸贴 URL，使用可读的链接名。
代码块
- 代码块必须标注语言：
- shell 命令：
bash（或 shell）
- YAML：
yaml
- JSON：
json
- 命令示例尽量可复制执行；需要环境变量/占位符时用
${VAR} 标示。
图片与资源
- 图片放在同目录或
assets/ 子目录，使用相对路径引用：
入口页（README）约定
目录下的 README.md 推荐只保留：
- 1-3 行简介
- 指向
handbook/ 对应主题的入口链接
- 可选：最多 3 条“最高频命令/操作”作为速查