mddoc-design（多文档设计）

向 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：

![脑图：<描述>](.mddoc/<name>.png)
*源文件：[<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：

![架构图：<描述>](.mddoc/<name>.png)
*源文件：[<name>.d2](.mddoc/<name>.d2)*

批量重新生成

mddoc build

反馈与问题

遇到问题或有建议，请到 GitHub 提 issue： https://github.com/drunkpig/md-of-programer/issues