写一份会议纪要、技术文档、读书笔记时，有时候用思维导图比纯文本更清晰——层级、并列、归纳关系一眼就能看出来。
但传统的脑图工具（XMind / MindManager / Lucidchart）要求拖框线、绑定线条颜色、调字号——做完一张图的时间够你写完三段正文。
markmap 的核心解法：直接用 Markdown 写。标题分层级、列表列要点，引擎自动出图。这篇从语法速成到 mermaid 对比，把它讲透。
最简语法：标题 + 列表
markmap 把 Markdown 文档解析成树状结构：
# Markmap 工具
## 语法
### 标题
- `#` = 根节点
- `##` = 一级分支
- `###` = 二级分支
### 列表
- `-` 同层并列
- 缩进 4 空格 = 下钻一层
## 富文本
- **加粗**
- *斜体*
- `code`
- [链接](https://example.com)
- emoji 🎯生成的导图：
Markmap 工具
├─ 语法
│ ├─ 标题
│ │ ├─ # = 根节点
│ │ ├─ ## = 一级分支
│ │ └─ ### = 二级分支
│ └─ 列表
│ ├─ - 同层并列
│ └─ 缩进 4 空格 = 下钻一层
└─ 富文本
├─ 加粗
├─ 斜体
├─ code
├─ 链接
└─ emoji 🎯核心规则：
| Markdown 元素 | 导图行为 |
|---|---|
# | 根节点（一般只有一个） |
## ### #### | 子层级，按数量递减 |
- 或 * 列表 | 同层并列 |
4 空格缩进的 - | 下钻一层 |
段落 > 引用 | 在节点下出现引用块 |
| 表格 | 直接渲染（节点里嵌表） |
富文本边界：哪些渲染哪些不
markmap 支持的 inline 富文本几乎和 Markdown 原生一致：
| 元素 | 写法 | 节点里渲染 | 导出保留 |
|---|---|---|---|
| 加粗 | **文字** | ✓ | ✓ |
| 斜体 | *文字* | ✓ | ✓ |
| 代码 | `code` | ✓ 灰底等宽 | ✓ |
| 链接 | [文字](url) | ✓ 可点击 | ✓ |
| emoji | 🎯 | ✓ | ✓ |
| 表格 | | 列 | 列 | | ✓ 节点里嵌入 | ✓ |
| 列表勾选 | - [x] 项 | ✓ | ✓ |
| KaTeX 公式 | $x^2$ | ❌ 渲染为字符串 | ❌ |
| 代码块高亮 | ```js ... ``` | ⚠️ 显示代码但不上色 | 同 |
两个限制的根本原因——本工具遵循”不连 CDN”原则，KaTeX 字体和 highlight.js 高亮规则文件都不会自动加载。
实务建议：
- 不要在导图节点里写公式——预览看着可能正常（字体兜底），导出后变成
$x^2$字符串 - 代码块尽量用 inline
code替代——只是为了区分代码与说明，inline 完全够用 - 如果一定要展示长代码 / 公式，放在导图同级的文档正文里，导图节点只保留概念名（“梯度下降公式”而非整段推导）
折叠与展开
点节点上的圆点——展开或折叠整支。
| 操作 | 行为 |
|---|---|
| 单击圆点 | 折叠 / 展开当前支 |
| 滚轮 | 缩放整张图 |
| 拖拽空白 | 平移视图 |
| 点”自适应” | 缩到适合容器 |
默认全部展开（工具配置 initialExpandLevel: -1）。复杂图（>30 节点）建议先折一遍：
- 先全展开看整体结构
- 折叠掉非重点分支（如示例数据、附录、参考链接）
- 留下当前要讲的支保持展开
- 点”自适应”重排
- 导出 SVG / PNG
导出会保留当前折叠状态——这是 feature 不是 bug，可以同一份大纲导出多张不同聚焦的图。
与 mermaid mindmap 的 4 点真实差距
很多人问：[[mermaid]] 已经有 mindmap 了，为什么还要 markmap？
1. 语法门槛
# markmap
## 分支A
- 要点1
- 要点2vs
mindmap
root((主题))
分支A
要点1
要点2mermaid 用缩进表示层级——必须严格对齐（通常 2 空格或 4 空格），少一个空格就报错。markmap 直接复用 Markdown，你写 README 的方式就能出图。
2. 富文本支持
- markmap：加粗 / 链接 / 代码 / emoji / 表格 / 公式（受限）
- mermaid mindmap：基本只支持纯文本 + 图标（
::icon(fa fa-book)），没有加粗、链接
3. 视觉精致度
- markmap：渲染基于 d3.js，节点距、布线、过渡动画都更细腻
- mermaid mindmap：和它其它图表风格一致——朴素、统一，没有专门优化
4. 生态与集成
- mermaid：GitHub / GitLab / Notion / 飞书 / 语雀都原生支持，你贴代码进 Markdown 就能出图
- markmap：渲染需要专门的工具或插件（如 VSCode 插件、独立网页版）
选择策略：
| 场景 | 选什么 |
|---|---|
| 技术文档配图、提交到 GitHub | mermaid mindmap |
| 复杂层级（4+ 层）、需要富文本 | markmap |
| 个人长文大纲、读书笔记 | markmap |
| 给同事远程协作看 | mermaid（生态广） |
| 视觉精致度高的演示图 | markmap |
5 类常见坏写法
1. 漏了根节点 #
## 分支A ❌
- 要点1没有 # 根节点，markmap 会用第一个 ## 兜底当根——但导图中心节点会缺失，外观奇怪。始终用 # 起头。
2. 缩进混用 Tab 和空格
- 父
- 子1 ← 4 空格
- 子2 ← Tab混用会被解析成不同层级，子1 和子2 在导图里平级看起来对，但格式校验严格的解析器（不同版本 markmap-lib）行为不一致。统一用 4 空格（不要用 Tab，不要用 2 空格）。
3. 节点文字超过 30 字
markmap 不会自动换行，长标题会撑出图框。修复：
- 把长句拆分成多个短节点（一条主干 + 几条子要点）
- 或用
<br>强制换行（inline HTML 支持）
## 这个非常长的分支标题就需要换行<br>第二行内容4. 表格塞了 10+ 行
markmap 节点里可以嵌表格，但表格行数 >5 时节点会变成一个大方块，破坏导图视觉重心。表格 ≥ 5 行的话改成列表或者放正文。
5. 把 mermaid 语法误写进 markmap
graph TD ❌ 这是 mermaid 不是 markmap
A --> Bmarkmap 只认 Markdown。两个工具用法完全不同——别复制错。
实战场景
读书笔记
# 《心流》摘要
## 核心概念
- **心流** = 全神贯注的最佳体验
- **挑战 vs 技能** 平衡
## 进入心流的 9 个条件
1. 清晰的目标
2. 即时反馈
3. 挑战与能力匹配
...
## 应用
- 工作中：把任务拆到刚好挑战
- 生活中：减少干扰源→ 导出 SVG 贴回笔记顶部当目录图。
项目分解
# 工具站 V2
## 前端
- ✓ Astro 框架
- ✓ Tailwind v4
- [ ] PWA 离线缓存
## 内容
- ✓ 193 个工具
- [ ] 教程扩充到 200+
## 运营
- [ ] 谷歌广告接入
- [ ] SEO 优化勾选框会在导图里渲染。
知识结构
# 前端工程化
## 构建
- Webpack
- Vite
- ESBuild
## 类型
- TypeScript
- Flow
- JSDoc
## 框架
- React
- Vue
- Svelte
- **Astro** *(本站使用)*加粗 + 斜体让重点节点突出，导出后贴博客或简历。
默认不做的事
- 不解析 Markdown 之外的元数据——Markdown 顶部的 YAML frontmatter 会被当成普通段落渲染
- 不自动加配色——节点颜色统一跟随主题，不像 XMind 给每支分支一个色（要分色得改 CSS 变量）
- 不联网渲染数学公式 / 代码高亮——见上文”富文本边界”
如果需要复杂的图表（流程图、时序图、ER 图等），用 [[mermaid]]；如果需要自由手绘（白板涂鸦、架构示意），用 [[whiteboard]]；如果是写 Markdown 文档本身，用 [[md-editor]]。markmap 专攻”Markdown → 思维导图”这一件事，用对场景就是最快的脑图工具。