Markdown深度实践：从语法到渲染，构建高效写作与文档工作流-平芜编程栈

从大学第一次写技术博客开始，我就一直在找一种"能让我专注于内容本身"的写作方式。试过Word，排版折腾半天，换个电脑样式就乱；试过网页版富文本编辑器，复制粘贴时格式满天飞；直到某天看到同事的README文件，纯文本却渲染得整整齐齐，我当时第一反应是：这玩意儿到底是怎么做到的？后来才知道，那个看起来平平无奇的文本格式叫Markdown。

这篇"Markdown浅析"不是教科书式的语法大全，而是我这些年把Markdown当成日常写作主力之后，沉淀下来的一整套真实经验。从语法细节到编辑器选型，从渲染原理到各种诡异报错的排查过程，再到Mermaid这类扩展语法怎么融入工作流，我都会聊。如果你正在用Markdown但总被各种小问题卡住，或者刚接触它想建立一套高效写法，这篇文章应该能帮你少走不少弯路。

1. 写文档这件事，为什么绕不开Markdown

很多人第一次接触Markdown，都会产生一个疑惑：用Word或者富文本编辑器直接排版不好吗，为什么非要学一种"带符号"的写法？这个问题我认真想过，答案其实藏在一次真实的团队协作事故里。

1.1 从一次团队文档事故说起

几年前我在一个项目组里，负责整理一份接口文档。当时用的是公司内部的在线文档平台，界面和Word很像，可以加粗、变色、调字号。我花了一下午把文档排版得漂漂亮亮，结果第二天需求变了，需要批量修改所有接口的请求参数。我复制粘贴了十几处，却发现有几个地方的格式完全乱了，粗体变成了普通文本，列表缩进乱七八糟。团队成员接手修改时更是头疼，每个人打开看到的样式都不一样，有人用Windows有人用Mac，渲染差异直接导致文档没法看。

这件事让我意识到一个核心问题：富文本格式看着方便，但它的"所见即所得"是建立在编辑器帮你维护一堆隐藏样式之上的。这些样式一旦跨平台、跨软件、跨版本迁移，就非常容易出问题。而Markdown的思路完全不同，它把格式这件事用纯文本约定来表达，你写**加粗**，不管在哪里打开，看到的都是同样的字符，渲染器再把它变成加粗。格式的"源代码"和"显示效果"是分离的，这天然就具备极强的可移植性和稳定性。

也是从那次之后，我开始认真把所有文档往Markdown上迁。README、接口文档、会议纪要、个人笔记、博客文章，几乎全是.md文件。现在哪怕过去三五年，打开当年的Markdown文件，样式仍然稳定，内容仍然清晰，这种"不过时"的体验是富文本很难给的。

1.2 Markdown的核心语法到底有多简单

Markdown能流行，除了稳定，还有一大原因是它真的简单到几乎没有学习成本。我记得自己大概花了十几分钟就记住了所有常用语法，之后基本不再查文档。

功能	语法	渲染效果
标题	`# 一级标题`、`## 二级标题`	各级标题
加粗	`加粗`	加粗
斜体	`斜体`	斜体
行内代码	`code`	`code`
代码块	```	独立代码块
链接	`[文字](https://example.com)`	链接
图片	`![描述](图片地址)`	图片
无序列表	`- 项目`	项目符号列表
有序列表	`1. 项目`	编号列表
引用	`> 引用`	引用块
表格	`	列1

这套语法覆盖了日常写作九成以上的需求，而且约定极其符合直觉：#越多标题越小，-代表列表，>代表引用。用生活类比的话，Markdown就像写作界的"乐高"，用少数基础零件就能拼出各种结构，而富文本编辑器像精装玩具，拿到手很漂亮，但想改装或者跨场地搬运就非常费劲。

正因为简单，Markdown才具备了比"标记语言"更高的身份——它成了一种写作习惯，甚至是一种数据交换格式。

所以我在后面谈各种编辑器、渲染器、插件时，都建议你先想清楚一件事：你的核心需求是"写"还是"看"。Markdown的优势永远在"写"这一端，它把写作的门槛降到最低；而"看"的效果，则由不同的渲染环境决定。理解了这一点，你就知道为什么同一个.md文件在不同工具里可能长得不一样，这不是bug，是生态的固有特性。

2. 语法细节里那些不起眼的坑：换行、表格、图片与目录

语法本身很简单，但真正用起来，很多卡住你的问题都出在"细节"上。这一节我把这几年高频踩到的坑挨个列出来，每一个都是热搜关键词的常客。

2.1 换行：一个回车在GitHub、Typora、VSCode里三种命运

如果你曾经在GitHub上写README，遇到过"明明换行了，显示出来却是一行"的问题，那么恭喜你，踩中了Markdown最经典的换行坑。

Markdown的换行规则和普通文本编辑器不一样。它把"两个回车"（即一个空行）视为分段，而"单个回车"只代表行内空格。换句话说，你写完一行后直接按一次回车，在很多渲染器（尤其是GitHub的GFM规范）里，下一行文本会接在上一行后面，而不是另起一行。

想要真正换行而不另起段落，有两个办法：

在行尾加两个空格，再按回车，这是Markdown官方标准做法；
直接空一行，让两段文字成为两个独立的段落。

但坑就坑在，不同编辑器的处理方式不一样。Typora属于比较"宠用户"的那种，你在它里面单按一次回车，视觉上就会换行，导出时也会帮你处理好；VSCode的预览插件两者都认；而GitHub的渲染器更严格，如果行尾没有两个空格又没有空行，它就会把两段连成一段。

我的实操建议很简单：如果稿件将来要发布到多个平台（比如GitHub、个人博客、公众号、知识库），统一采用"敲空行分段"的写法，不要依赖行尾加空格。因为两个空格在有些编辑器里看不见、容易误删，而空行是任何渲染器都能正确识别的。

2.2 表格与复制的血泪史

Markdown表格语法在GFM里才被正式支持，所以早期的Markdown根本不能画表格。现在大家用的都是竖线加横线的方式：

| 姓名 | 岗位 | 城市 | | --- | --- | --- | | 张三 | 后端工程师 | 北京 | | 李四 | 前端工程师 | 上海 |

语法本身不复杂，但在实际使用中，最让人抓狂的是"表格复制"。

你从Excel或者在线表格里复制一段数据，直接粘到Markdown编辑器，往往得到的是Tab分隔的纯文本，而不是一个规范表格。反过来，从Markdown渲染好的表格复制到Excel或Word，也经常乱掉。

我自己的做法是分场景处理：

从Excel到Markdown：先在Excel里选中区域复制，再到支持"粘贴为表格"的编辑器（比如Typora）里粘贴，Typora会自动把Tab分隔的文本转成Markdown表格。如果用的是VSCode，可以装一个"Markdown Table Prettifier"插件，配合Paste操作也能快速整理。
从Markdown到Excel：不要直接复制渲染后的表格内容，而是复制源码再转换。最省事的办法是用VSCode插件"Excel to Markdown Table"，反过来也支持。
表格内容过多时：不建议手写，太重。我一般先用在线工具（比如Table Convert）把CSV或Excel转成Markdown，再粘贴进编辑器。

表格复制的本质问题是：Markdown表格是一种"文本表现"，而Excel是一种"结构化数据表现"，两者之间的转换需要经过解析和重组，任何工具都只能做到"尽可能智能"。所以遇到复制乱掉时，先检查原始数据是不是纯文本、有没有合并单元格、有没有特殊符号，排除了这些，转换成功率会高很多。

2.3 图片引入与路径问题

Markdown里插入图片用的是![描述](图片地址)。听起来简单，但图片地址怎么填，这里面的门道非常多。

本地相对路径：

![架构图](./images/arch.png)

这种写法适合项目文档放在Git仓库里，图片和文档一起提交。优点是可移植、离线可看；缺点是如果目录层级调整，相对路径就失效了，而且一旦图片丢失，文档就缺图。

本地绝对路径：

![架构图](/Users/me/notes/images/arch.png)

这种写法只适合本地个人笔记，不推荐用于任何需要分享的文档。换台电脑路径就废了。

在线URL：

![架构图](https://example.com/images/arch.png)

适合博客、文章、官方文档，图片托管在图床或对象存储上。需要注意：如果图床域名失效，图片就挂了。

还有一个高频痛点是"粘贴图片"。Typora和很多编辑器支持直接截图粘贴，并自动保存到指定文件夹。我一般会在文档根目录建一个assets文件夹，编辑器设置里把图片保存路径指过去。这样整体结构是：

docs/ ├── 文章.md └── assets/ └── 文章-2025-01-01.png

这个习惯让我在写长文、迁移Note库时省了很多事。

另外，如果你是写博客或者公共文档，强烈建议图片统一走图床或对象存储，并且图片命名不要用中文和空格，比如架构图 v2（最终）.png这种命名在URL解析时很容易出问题。

2.4 目录到底怎么生成

还有一个被反复搜索的问题：VSCode里怎么把Markdown文件的目录显示出来。

这里要区分两个概念：一是"文件结构的大纲"（Outline），二是"文档内的TOC目录"。

VSCode大纲：VSCode自带资源管理器下方的"大纲"面板，默认会把Markdown的标题层级按大纲展示。如果你没看到，可以在资源管理器面板的上方工具栏点击"..."，勾选"大纲"。这里显示的是当前文档的标题树，点击即可跳转，但它只是编辑器辅助功能，不会出现在导出文档里。

文档内TOC目录：如果你希望文章开头能有一个可点击的目录列表，最方便的做法是安装插件"Markdown All in One"。它提供了Markdown All in One: Create Table of Contents命令，可以按当前文档标题自动生成目录，格式大致像：

- [1. 写文档这件事，为什么绕不开Markdown](#1-写文档这件事为什么绕不开markdown) - [1.1 从一次团队文档事故说起](#11-从一次团队文档事故说起)

这个目录本质上是Markdown链接列表，在GitHub、VSCode预览、Typora里都能正常跳转。我用下来唯一的建议是：文档写完后再生成一次TOC，不要边写边生成，否则标题一改目录就失效，还得重新跑命令。

3. 编辑器选型：Typora、VSCode、Obsidian和他们都解决什么问题

Markdown的编辑器数以百计，每一款都在"写"和"看"之间做了不同的取舍。我先后用过多款，这里聊聊它们的差异和适用场景。

3.1 Typora：极简的实时预览为什么让人上头

Typora是我用了最久的一款桌面编辑器。它的核心理念是"所见即所得"，但和传统的富文本编辑器不同，它不是在一个Rich Text控件里改样式，而是把Markdown源码隐藏起来，直接渲染成最终效果。

比如你在Typora里输入一个#加空格，再输入文字，界面会立即显示为一级标题，而不是显示# 标题这种源码。当你把光标挪到那段文字上，Typora又会临时显示出Markdown源码结构，方便编辑。这种"源码和渲染无缝切换"的设计非常舒服，写作沉浸感很强。

Typora的适用场景是：纯写作、博客排版、笔记整理。它的主题丰富，导出PDF、HTML的效果很漂亮，而且支持自定义CSS。不过它的编辑能力和程序员常用的代码编辑器相比弱一些，如果你想在同一个界面里既写Markdown又跑终端或者看Git提交记录，它就不合适了。

3.2 VSCode + 插件：程序员手里的万能Markdown环境

VSCode是程序员群体里最常见的Markdown编辑环境。它本身的Markdown预览已经很能用，配合插件之后，功能可以逼近甚至超过很多专业Markdown编辑器。

我平时在VSCode里必装的几款插件：

Markdown All in One：自动生成目录、快捷键、自动格式化表格，是"最值得装"的一款，我上面提到的目录生成就靠它。
markdownlint：检查Markdown语法规范，比如标题层级是否跳跃、行尾空格是否符合规范。写公共文档时非常有用，能提前发现很多潜在的渲染问题。
Paste Image：截图后直接粘贴成图片文件，并自动插入Markdown图片语法。我配合assets文件夹使用，工作流非常顺。
Markdown Preview Enhanced：增强预览效果，支持导出HTML、PDF，还能渲染Mermaid图、数学公式、PlantUML，功能很全面。
Excel to Markdown Table：把Excel表格转换为Markdown表格，解决我上面提到的表格复制问题。

VSCode里还有一个很多人不知道的实用功能：Ctrl+Shift+V可以打开预览面板；Ctrl+K V可以打开侧边实时预览。写文档时一边编辑一边看效果，效率比单纯盲写高很多。同时，VSCode的Outline大纲面板支持按标题索引，和Markdown All in One的TOC生成互补。

如果非要挑VSCode的缺点，那就是初始配置成本比Typora高，默认字体、主题、缩进都需要自己调一版。

3.3 笔记场景的Obsidian和其他候选

Obsidian是笔记场景的"神兵利器"。它的核心创新是双链（Backlink），可以在不同笔记之间建立关联，形成一个个人知识网络。Markdown在这里不仅是格式，更是知识库的基础单位。

你可以用[[笔记名]]的方式引用其他笔记，Obsidian会生成一个图谱视图，所有笔记之间的引用关系可视化展示。我刚开始觉得这功能是花架子，后来真用起来才发现，当笔记量超过几百篇时，双链能让知识检索从"文件夹归类"升级为"内容关联"，这完全是两种使用体验。

Obsidian的本体也是Markdown编辑器，支持实时预览、表格、Mermaid，配合社区插件几乎可以定制成任何你想要的样子。如果你愿意把大量个人笔记管理起来，我建议优先考虑Obsidian。

其他候选：

编辑器	特点	适用场景
Notion	数据库、页面嵌套，块编辑器	团队协作、知识库管理
语雀	结构化文档、小记	团队知识沉淀
Joplin	开源、跨平台、端到端加密	隐私敏感的个人笔记
StackEdit	在线编辑器，支持同步	临时写作、浏览器环境

其实没有绝对"最好"的Markdown编辑器，只有"更适合你当前工作流"的编辑器。我自己是Typora配Obsidian配VSCode三件套：Typora写博客初稿，Obsidian管理长期笔记库，VSCode做代码和文档混合开发。三者之间的.md文件可以无缝互换，这也是Markdown赋予我的最大自由。

4. 渲染与转换：Markdown如何变成HTML、Word和其他一切

Markdown本身只是文本规范，它真正发挥作用，靠的是渲染器。这一节我会从底层逻辑出发，讲清楚Markdown是怎么变成HTML、Word的，以及近年来特别火的"流式渲染"到底在解决什么问题。

4.1 Markdown渲染成HTML的底层逻辑

Markdown渲染成HTML的过程可以拆成三步：

解析（Parsing）：把Markdown文本按语法规则拆解成一棵抽象语法树（AST），标记出哪些是标题、哪些是段落、哪些是列表。
转换（Rendering）：把AST转成HTML结构，比如# 标题变成<h1>标题</h1>。
样式（Styling）：HTML结合CSS进行最终渲染。

市面上的渲染器五花八门，但核心都是这三步。前端领域常用的解析库有：

marked：轻量、速度快，适合简单场景。
markdown-it：插件生态好，支持自定义规则，适合需要扩展的场景。
remark：基于统一语法树（unified）生态，适合做复杂的文档处理流水线。

如果你用的是Vue，要在页面上解析并显示Markdown，最常见的方案是引入markdown-it，然后通过Vue组件把编译后的HTML渲染出来。

<template> <div v-html="renderedContent"></div> </template> <script setup> import { computed } from 'vue'; import MarkdownIt from 'markdown-it'; const md = new MarkdownIt({ html: true, linkify: true }); const props = defineProps({ content: String }); const renderedContent = computed(() => md.render(props.content)); </script>

这里有个安全提醒：如果Markdown内容来自用户输入，直接使用v-html或innerHTML渲染有XSS风险。一定要先用DOMPurify等库对HTML做清理，或者使用默认禁用HTML标签的渲染配置。

4.2 转Word的实用路线

虽然Markdown在纯文本场景很强大，但现实中总是有"要交Word文档"的需求，比如技术方案要发给不接触Markdown的同事，或者论文、报告需要按固定模板提交。

最标准、最可靠的方案是Pandoc。这是一款命令行文档转换瑞士军刀，支持Markdown与Word、HTML、PDF、LaTeX等几十种格式互转。

基本用法很简单：

pandoc input.md -o output.docx

Pandoc转Word时，会生成一个docx文件，里面的标题样式基于Word的"标题1""标题2"等预设样式，好处是适合二次排版。如果你想要自定义模板，可以先导出一份参考docx，再修改样式：

pandoc input.md -o reference.docx --print-default-data-file reference.docx > custom-reference.docx pandoc input.md -o output.docx --reference-doc=custom-reference.docx

如果你不想碰命令行，还有图形化的路线：Typora直接支持"文件 -> 导出 -> Word"，内部其实也是调用Pandoc。所以装好Pandoc并配置到Typora里，就能在菜单栏直接输出docx。

至于"markdown转word工作流coze"这个方向，我理解大家想要的是把转换流程自动化。Coze这类工作流平台可以编排一个自动化流程：收到Markdown文本 -> 调用转换接口或脚本 -> 生成Word并输出。实际落地时，最简单的做法是写一个接收.md文件、调用Pandoc、输出docx的脚本，再用工作流平台去调度，比如：

在Coze中配置一个节点接收文件输入；
调用本机或服务器的Pandoc脚本完成转换；
返回生成的Word文件给用户。

核心还是要有一个能执行Pandoc的环境。工作流真正解决的只是"把多个步骤串起来"，而不是替代Pandoc本身。

4.3 SSE流式输出中的Markdown渲染：AI对话场景的实战

近几年大模型对话系统爆发，"SSE流式输出Markdown渲染器"成了一个被高频搜索的词。这个词听起来高大上，实际场景其实很常见：你在对话框里问AI一个问题，AI逐字输出回答文本，这些文本通常包含Markdown格式的代码块、列表、标题，前端需要实时把正在生成的内容渲染成网页样式，而不是等全部输出完再一次性渲染。

SSE（Server-Sent Events）是一种服务器向客户端单向推送数据的技术，非常适合这种逐字输出场景。但流式渲染Markdown有一个经典难题：

半截语法问题。假设AI正在输出一个代码块，它先流出了```python三个反引号，然后是代码内容，最后才是结尾的三个反引号。如果每收到一小段文本就用完整Markdown渲染一次，那么中间状态（比如只有开头反引号、没有结尾反引号）会被解析成"一个未闭合的代码块"，界面就可能显示成普通文本或者一个巨大的代码块把页面撑爆，导致闪烁和跳动。

我踩过这个坑之后，总结了几条解决思路：

缓冲区累积渲染：不要把每一小段都单独渲染，而是把已收到的文本累积起来，在渲染前做节流（比如每100ms渲染一次）。这样即使语法不完整，由于整体内容增量，渲染结果也会比逐字渲染稳定得多。
容错解析：使用markdown-it时，可以配置breaks和linkify选项，并允许HTML；对"未闭合的代码块"这类情况，在流式过程末尾追加临时闭合内容，确保解析器不会进入异常状态。
延迟加载代码高亮：对代码块高亮，不要在流式过程中就立即对半截代码做高亮，等代码块完结后再触发高亮，避免高亮状态错乱。
平滑滚动：流式渲染后内容高度变化剧烈，需要将页面滚动锚点稳定在用户正在阅读的位置，不然文本会跳来跳去。

具体到代码模型，一个简化版思路：

let buffer = ''; const md = new MarkdownIt(); function onChunk(chunk) { buffer += chunk; const safeContent = buffer + '\n```\n'; // 临时闭合可能未闭合的代码块 preview.innerHTML = md.render(safeContent); }

最终输出前，用完整内容重新渲染一次，去掉临时闭合内容。这个思路我实测下来效果稳定，能大幅减少AI对话界面里常见的"代码块闪烁"问题。

5. 踩坑实录：Typora多开、JCEF报错与小程序显示

每个用Markdown的人都会遇到几个奇奇怪怪的报错或者反直觉的操作，下面这三个是热搜词里出现频率最高的，我挨个说清楚当时的排查过程。

5.1 Typora为什么只能打开一个窗口

我当时在Windows和Mac上都遇到过这个问题：双击第二个.md文件，Typora没有新开窗口，而是闪了一下，然后回到了已经打开的那个窗口，第二个文件的内容没显示出来，或者得手动去菜单切换。

排查过程：

一开始我以为是文件关联的问题，重新设置了.md文件的默认打开方式，无效。
后来怀疑是软件装了两个版本冲突，卸载重装，还是无效。
翻官方文档后才发现：Typora目前是"单窗口"设计。它的定位是"所有文件都在一个窗口里管理"，默认情况下双击文件只是让已有窗口获得焦点，并把文件打开为窗口里的一个标签页，而不是新开一个窗口。

如果你就是想在多窗口里同时编辑多份文档，我的解决办法是：

打开Typora后，用"文件 -> 打开"选择文件，它会在同一个窗口的新标签页中打开。
如果你确实需要两个独立窗口，可以再打开一个Typora进程（跨平台用户可使用启动器多开），但这个操作不优雅，容易在一个窗口里产生文件锁问题。
更推荐的习惯是：把Typora当作"单文档聚焦写作"工具，一个窗口专注于当前文章；需要多文档对比、批量管理时，切换到VSCode或Obsidian。

总之，Typora多开报错不是bug，而是产品设计取舍。理解了它的定位，就理解了为什么官方一直没加"多窗口"这个功能。

5.2 "Your environment does not support JCEF" 是什么鬼

这条报错我在JetBrains系IDE（比如IntelliJ IDEA、PyCharm）里装Markdown插件时见到过。完整报错大概长这样：

Your environment does not support JCEF, cannot use Markdown Editor

人话解释一下：JCEF（Java Chromium Embedded Framework）是JetBrains IDE中用来在Java应用里嵌一个Chromium内核的组件，很多富文本预览、网页渲染功能都依赖它。你的IDE检测到当前环境不支持JCEF，所以Markdown编辑器的富文本预览功能就被禁用了。

出现这个报错常见原因有几种：

JDK版本太老或者太新，JCEF版本不匹配；
IDE跑在无图形界面的远程环境、某些服务器环境、或者受限的云桌面环境；
系统缺少Chromium运行所需的图形库；
IDE的内存配置不满足JCEF加载要求。

我这边的排查记录是：当时在一台远程开发服务器上用IDEA，本地Windows打开同样的项目没问题，但在远程桌面环境里就报了这个错。仔细排查后发现，是远程环境缺少了Graphics相关的Linux库，导致JCEF初始化失败。

如果你是本地环境遇到这个错，可以按以下顺序排查：

确认IDE已经更新到最新版，JCEF通常随IDE版本一起升级；
检查JDK版本，IDE自带的JBR（JetBrains Runtime）一般带JCEF，尽量避免手动覆盖；
尝试在IDE设置里开启或关闭"ide.browser.jcef.debug"等JCEF相关开关；
如果是远程/容器环境，检查图形库、X11转发或改用无头模式；
实在不行，可以把Markdown插件降级为纯文本编辑模式，或者改用VSCode。

关键建议：不要一上来就重装IDE。先判断你的使用环境里JCEF是否被系统级因素拦截，再决定下一步。

5.3 小程序到底能不能显示Markdown

这个问题的答案是：小程序本身不内置Markdown解析和渲染能力，但可以通过引入第三方组件库来实现。

很多人把Markdown粘贴到小程序里，发现它不会自动变成格式化内容，因为小程序的text组件只能显示纯文本，rich-text可以显示HTML，但也不会解析Markdown语法。

实际可落地的方法有两类：

方案一：引入towxml开源库

towxml是一个专门用于在小程序中渲染Markdown和HTML的库，支持表格、代码高亮、LaTeX、Mermaid等，是社区里比较成熟的小程序Markdown方案。使用方式大致是：

把towxml库拷贝到小程序项目中；
在页面json配置里注册towxml组件；
用一个自定义组件包裹Markdown内容，towxml会把Markdown解析成WXML结构。

这种方式的好处是纯前端解析，无需额外服务端；缺点是库本身有体积，首次加载会略慢。

方案二：服务端把Markdown转成HTML，小程序用rich-text渲染

如果你有服务端，可以让后端在返回内容时用markdown-it/marked把Markdown转成HTML字符串，小程序前端用rich-text组件直接渲染。

<rich-text nodes="{{htmlContent}}"></rich-text>

这种方式实现成本最低，而且样式可控制。缺点是需要处理XSS风险，以及rich-text对部分HTML标签和行内样式的支持有坑，某些CSS属性不生效。

我做小程序项目时更推荐方案二，因为前端代码量少、渲染性能可控，而且内容清洗可以在服务端统一做。不过要提醒一点：小程序端如果对内容有敏感词审查、链接跳转、图片点击预览等需求，纯rich-text的交互能力有限，需要在解析层做更多定制。

6. 让Markdown变得强大的扩展语法：Mermaid与更多

Markdown如果只有基础语法，撑死算个"美化版纯文本"。它真正能成为一种通用内容格式，靠的是丰富的扩展语法。这几年对我帮助最大的，就是Mermaid。

6.1 用Mermaid在Markdown里画流程图

Mermaid是一种基于文本的图表描述语言，它允许你通过简单的代码在Markdown文档里画流程图、时序图、类图、甘特图等。这意味着图表不再是"图片附件"，而是和文字一样可以进行版本管理、Diff追踪的纯文本。

一个最简单的流程图写法：

graph TD A[开始] --> B{判断条件} B -- 是 --> C[执行操作] B -- 否 --> D[结束]

在支持的编辑器里，它会渲染成一张完整的流程图；在不支持的普通文本编辑器里，它至少也是一段可读的文本。

我实际感受最深的场景是写技术方案时。以前画架构图得用Visio或draw.io，画完导出png再贴到Word里；现在直接在文档里写Mermaid，改起来也方便，一行代码就能改一个节点名称，不用重画整张图。

不同环境怎么渲染Mermaid：

Typora：内置Mermaid支持，代码块语言选择mermaid即可实时预览。
VSCode：Markdown Preview Enhanced插件支持Mermaid渲染。
GitHub：GitHub的Markdown原生支持Mermaid代码块。
Obsidian：默认支持Mermaid，也可以安装插件增强。
飞书文档：很多人问飞书要装什么插件才能解析Markdown里的Mermaid，其实飞书云文档原生支持粘贴Mermaid代码块后渲染成图的。你新建一个代码块，把语言选为"Mermaid"，或者直接粘贴```mermaid代码块的文本内容，飞书往往能识别并渲染。但要注意，飞书的Markdown是一种简化版，不保证所有GFM语法都支持，所以最稳妥的方式是把Mermaid代码块放进飞书文档的代码块里，看它是否自动渲染；如果不行，就在代码块内右击查看有没有"预览图表"选项。不同版本功能可能差异，最终还是要以你手头版本为准。

如果你自己开发一个Markdown编辑页面，想支持Mermaid，可以引入mermaid的JavaScript库，在渲染完HTML后扫描代码块并调用mermaid.run()初始化。这里我唯一的经验提醒：Mermaid渲染动画比较重，如果文档里有大量图表，建议设置securityLevel并延迟初始化，避免页面卡顿。

6.2 其他值得关注的扩展

Mermaid只是Markdown扩展生态的一角，还有几个高频用到的扩展语法：

Front Matter：在文档开头用---包裹一段YAML元数据，常用于静态博客或笔记工具。比如：

--- title: Markdown浅析 date: 2025-01-01 tags: [Markdown, 写作] ---

数学公式：通过$符号包裹LaTeX公式，Typora、Obsidian、GitHub的Markdown都支持。行内公式用 $...$ ，块级公式用$$...$$。

任务列表：GFM支持的任务列表语法：

- [x] 已完成 - [ ] 待完成

脚注：在Typora、Pandoc等场景下支持：

这是一个句子[^1]。 [^1]: 脚注内容。

删除线：用~~文本~~实现删除线效果，在协作审阅场景下很好用。

这些扩展都是建立在Markdown"约定规范"之上的。使用时要记住一点：扩展语法不一定被所有渲染器支持，如果你的文档要跨平台发布，建议先用兼容性最好的基础语法，扩展语法只在确定目标平台支持的情况下使用。

我自己写博文时，几乎只用基础语法加代码块；写技术方案时才会用Mermaid和表格；写个人知识库时会用Front Matter和双链。怎么组合，完全取决于你要发布到哪、给谁看、维护成本多大。

最后再分享一个小经验：不管你用哪个编辑器，记得养成定期把Markdown文件纳入版本管理的习惯。用Git管理.md文件，比任何富文本格式的"自动保存"都可靠。遇到改坏了、想回退、想比较前后差异的时候，Git配合Markdown纯文本的特性，能给你带来一种难以言喻的安全感。这也是我用Markdown几年下来，最值得的一个决定。