向 Markdown 文档插入图表时，始终遵循以下规则。
依赖检查
开始任何操作前，先检查依赖是否已安装：
which mddoc && which d2
若 mddoc 未安装：
npm install -g mddoc-cli
若 d2 未安装：
- macOS：
brew install d2 - Windows：
winget install terrastruct.d2 - Linux / 其他：参考 https://d2lang.com/tour/install
两个都就绪后再继续。
规则
- 所有图表源文件和 PNG 只放在
.mddoc/目录（与 Markdown 文件平级） - 文件名用英文小写 + 连字符（
auth-flow、module-overview），不用中文或序号 - 先写源文件，再生成 PNG，再插入 Markdown，顺序不可颠倒
- Markdown 正文中永远不要直接写 D2 或 markmap 代码块
.mddoc/不存在时先创建
脑图（.mmd）
1. 写源文件 → .mddoc/<name>.mmd，格式为 markmap markdown：
# 根节点标题
## 一级分支
- 叶节点
- 叶节点
## 一级分支
- 叶节点
- 二级叶节点
2. 生成 PNG：
mddoc mindmap .mddoc/<name>.mmd
3. 插入 Markdown：
*源文件：[<name>.mmd](.mddoc/<name>.mmd)*
架构图（.d2）
1. 写源文件 → .mddoc/<name>.d2，格式为 D2 语言：
direction: right
client: 客户端 {shape: rectangle}
gateway: API Gateway {shape: rectangle}
db: Database {shape: cylinder}
client -> gateway -> db
2. 生成 PNG：
mddoc arch .mddoc/<name>.d2
3. 插入 Markdown：
*源文件：[<name>.d2](.mddoc/<name>.d2)*
批量重新生成
mddoc build
反馈与问题
遇到问题或有建议，请到 GitHub 提 issue： https://github.com/drunkpig/md-of-programer/issues