我写文档写了快十年，Markdown 语法在我这儿属于“十分钟入门、十年里反复踩坑”的东西。上周又翻了一次车：同一份 md 文件，在 Typora 里排版得干干净净，推到 GitLab 上却整段黏在一起，两个小时没人发现，直到评论区有人问“这段是不是忘了分段”。我后来才发现，问题出在一个绝大多数人不会细想的细节——换行。你可以在技术社区里同时搜到 python 语法、shell 语法、正则表达式语法和 Markdown 语法，后者看起来最简单，但它恰恰因为太简单，反而被很多人当成“会了”，结果一到多平台发布就原形毕露。
这篇东西打算把我这些年用 Markdown 踩过、修过的坑集中整理一下。不打算把语法表从头抄一遍，重点讲那些在不同平台、不同工具之间会“变脸”的细节，以及我长期验证下来比较稳的写法。适合写 README、维护团队文档、发公众号文章、做个人笔记的朋友参考。
1. 换行这件小事，足以让你在 Git 平台和编辑器里看到两篇“文章”
1.1 三种换行写法，分清楚就不再抓狂
Markdown 里“换行”至少有三种含义，很多人混为一谈。
第一种是段落分隔：两段文字之间空一行。渲染结果是两个独立的段落，段与段之间有明显的垂直间距。这是最推荐的方式，语义最清晰，几乎所有解析器都认。
第二种是硬换行：在一行末尾敲两个空格再回车。渲染结果是同一个段落内部折行，行尾产生一个<br>。这在诗歌、地址、代码行内注释等需要精确换行的场景下有用。第三种是软换行：直接按一次回车，不加任何东西。大多数解析器会把它当成一个普通空格，意思就是“你虽然换行了，但渲染时文本还是连在一起的”。
还有一部分实现支持行尾加反斜杠\来换行，这是 Markdown Extra 和 GFM（GitHub Flavored Markdown）常用的写法，比两个空格更直观，但老式解析器不认。
| 写法 | 渲染结果 | 通用性 |
|---|---|---|
| 空一行 | 独立段落 | 所有解析器 |
| 行尾两个空格 | 段内换行 | 标准 Markdown，最稳 |
| 行尾反斜杠 | 段内换行 | CommonMark / GFM 大多支持 |
| 直接回车 | 合并为空格 | 最常见误解来源 |
1.2 为什么同样的 md 文件渲染结果会不一样
这是我近几年反复跟人解释的一个问题。你在 Typora 里敲回车，屏幕上确实换行了，于是你以为这份文件“就是换行”。但 Typora 是所见即所得编辑器，它把软换行直接显示成了视觉上的换行。GitHub、GitLab 这些平台走的是 CommonMark / GFM 解析器，单个回车按规范就是合并成空格，不会替你产生换行。
于是同一份文件，在编辑器里是一个样子，推到远端仓库是另一个样子。问题不在文件，在于你把“编辑器的显示效果”当成了“渲染后的真实效果”。
更麻烦的是，不同平台还有自己的小脾气。钉钉机器人消息里支持一部分 Markdown，但表格和数学公式基本不渲染；语雀、飞书有自己的解析器；公众号编辑器更是只认富文本，Markdown 要先把转成带内联样式的 HTML 再粘贴。所以同一个 md 文件换一个平台就“变脸”，不是 bug，而是平台对 Markdown 语法的解析各自为政。
1.3 我这些年固定下来的换行规范
踩过几次坑之后，我的规则很简单：
- 正常段落之间一律空一行，不要用两个空格去“假装分段”。
- 列表项内部不换行；如果需要多行说明，拆成多个列表子项，或者另起段落。
- 必须折行的地方（比如配置示例、运行结果展示），优先用行尾两个空格，因为兼容性最好。
- 如果团队协作，建议在 CI 或编辑器里挂 markdownlint，开启 MD009（尾随空格检查）、MD012（多个连续空行检查）规则，把换行风格变成自动化检查项。
这个习惯坚持了两三年，GitLab 上“文档黏成一块”的问题再没出现过。
2. 列表、代码块和引用块：缩进与空行说了算
2.1 嵌套列表改个缩进就全乱套
嵌套列表应该是最容易“看起来会了，一写就错”的部分。无序列表用-、*、+都行，有序列表用1.2.。但一旦要嵌套，问题就来了。
子列表项需要在父列表项下方，缩进两个空格或更多。这里有个隐蔽的坑：父子列表项之间不要空行。一旦空行，很多解析器会把子列表当成一个全新的列表，导致编号重置、缩进失效，甚至渲染成平级列表。
另一个坑是 Tab 键。我见过不少同事在编辑器里按 Tab 缩进嵌套列表，本地看没问题，推到 GitHub 上就乱。因为不同平台对 Tab 的宽度解释不一致，稳妥的做法是关闭“Tab 转换为空格”的选项，统一用空格缩进。
还有一个小知识：GFM 支持自定义有序列表的起始数字，比如写3. 第一步，渲染后会从 3 开始编号。这在写分步骤说明时很实用，但要注意有些平台不认。
2.2 代码块的语言标注与高亮失效
插入代码块有三类常见需求，正好对应“markdown 插入 code”这个搜索词。
行内代码用反引号包裹，比如`npm install`。如果代码本身包含反引号，可以用双反引号包一层。
块级代码推荐围栏式，也就是三个反引号加语言名：
```python print("hello") ```语言标注不生效，通常是三个原因：拼写错误、标注后跟了空格、用了全角反引号。GitHub 不会报错，只会悄悄不高亮。另外，缩进式代码块（行首缩进四个空格）我不推荐，尤其别放在列表项里，很容易被解析成普通文本或子项。
在列表项里嵌代码块也要小心：围栏式代码块本身要跟着列表项缩进，否则看起来在列表里，渲染时却跳到了列表外面。
2.3 引用块里能放的东西比你想象的多
引用块用>开头，>后面加不加空格都行，但加空格更稳。多层嵌套引用用>>。
很多人不知道引用块内部可以做很多事：可以写标题、加粗、列表，甚至嵌套引用。但要注意，引用块内部的段落之间同样要空行，否则会被合并成一段。
我在团队文档里常用的“提示框”写法其实很简单：
注意：这里放提醒内容，GitHub、GitLab、Typora 都能正常渲染成引用样式。
这套写法规避了平台对“提示框”扩展语法支持不一致的问题，哪怕平台完全不懂 Markdown 扩展，它至少还是一个可读的引用块。
2.4 行内代码、加粗斜体与转义边界
这些细节看起来琐碎，但都是真实踩坑点。
- 加粗用
**text**，中间不能有空格。** text**这种写法在标准解析器里不生效。 - 斜体可以用
*text*或_text_。在 GFM 里，_在单词内部（如foo_bar）不会被当成斜体，而*会。如果你想在文档里写foo_bar这种变量名，用*包反而容易误伤。 - 删除线
~~text~~在 GitHub 是原生语法，但部分平台不支持。 - 特殊字符需要转义，包括
\*_`[]{}#+-.!。 - 行内代码里写 Markdown 符号不会被解析。比如
`**not bold**`会原样显示**not bold**，不用担心。
如果你要在一个文档里大量写变量名、命令行参数，建议直接统一用行内代码包裹，省去转义的心智负担。
3. 图片路径、图床与“图裂”修复实战
3.1 三种图片路径各有边界
Markdown 图片语法是，看起来人畜无害，问题几乎都出在“路径”上。
相对路径适合“仓库型文档”：文档和图片放在同一个 Git 仓库里，用assets/xxx.png或./img/xx.png引用。好处是仓库整体迁移、克隆后图片不丢。坏处是层级一多，路径容易写错。
绝对路径适合部署在服务器上的文档站，比如/static/img/xxx.png。但如果你换域名或改目录结构，所有图片会一起裂，维护成本不低。
URL 图床适合博客、公众号这类面向公网的内容，访问速度快，文章里不用维护本地文件。但图床一挂，全文图片失效；如果图床做了防盗链，换个平台引用还会被拦截。
还有一个小技巧：GitHub 和 Typora 都支持直接用 HTML 标签控制图片尺寸，比如<img src="xxx.png" width="400">。这种写法不是标准 Markdown，但在很多平台可用。
3.2 为什么从云笔记导出的 md 总是丢图
“从语雀导出”“从有道云导出”“从 Notion 导出”之后图片裂成一片，是高频问题。原因很简单：这些工具把图片存在自家图床或私有存储上，导出 Markdown 时给的是带签名、带时效的 URL。签名过期，或者你把文件拷到另一台电脑，图片就裂了。
有些工具导出的是 HTML 里嵌着 base64 的图片，转成 md 时这部分信息干脆被丢弃；还有些工具会导出一个带资源文件夹的压缩包，但你只拖走了 md 文件，忘了把文件夹一起拷走。
所以我自己定了一条规矩：任何在线编辑器导出的 md，拿到手先做一次“图片完整性检查”，不要直接当交付物扔出去。检查方式很简单——看下所有指向的路径是否存在，或者写个小脚本把所有外链图片批量下载到本地。
3.3 让文档“搬家不裂”的 Typora 与仓库化方案
如果你经常用 Typora，我建议去“偏好设置 → 图像”里做两件事。
第一，插入图片时勾选“复制图片到指定路径”。路径我习惯设成./assets，也就是文档同目录下的 assets 文件夹。第二，把“优先使用相对路径”打开。这样在文章里写图片时，typora 会自动复制图片并生成assets/xxx.png这样的引用。
这个方案配合 Git 仓库很舒服。整个文档库克隆到任何机器上，图片都跟着走，不依赖外网、不怕图床失效。
如果你的历史文档里已经有大量外链图片，可以用脚本批量下载。脚本逻辑不复杂：用正则找到所有https://...形式的图片链接，下载到 assets 目录，再把 Markdown 里的 URL 替换成本地相对路径。做完后跑一遍git diff检查改动范围，确认没有误伤。
3.4 网页转存 Markdown 的 skill 到底在做什么
现在挺流行“agent 将网页保存成 markdown 的 skill”，很多人以为是个黑魔法，其实核心就是内容抽取。我自己写过类似脚本，流程大概是：
- 打开页面，必须等 JS 渲染完，直接抓 HTML 常常只拿到空壳。
- 用可读性算法抽正文，把导航、侧栏、评论、广告全部去掉。
- 把网页里的
h1h2标题层级归一化，很多网页会用div模拟标题，顺序乱跳。 - 处理图片：判断是懒加载还是
srcset，下载到本地并替换路径。 - 清理空标签、空段落，最后输出标准 Markdown。
判断这类工具好不好用，就抓一篇带表格、带代码块的知乎文章试试。如果表格被压成一行、代码块语言标注丢了，那这工具还不能拿来干正经活儿。我自己用这类工具之后，永远会人工检查一遍开头、结尾和图片路径，再进入知识库。
4. 表格、数学公式、Callout 与任务列表：GFM 的进阶玩法
4.1 表格语法本身很简单，坑在解析器
GitHub 标准的表格语法是：
| 功能 | 命令 | | :--- | ---: | | 安装 | `npm i` | | 卸载 | `npm rm` |表头下面是分隔行，分隔行里冒号的位置决定对齐方式：:---左对齐，:---:居中，---:右对齐。
几个实际注意点：
- 表格前面务必空一行，否则某些解析器不识别为表格。
- 单元格里出现竖线
|时要转义成\|，否则会把表格撑裂。 - 单元格内容不要塞太长段落，更不要放代码块、嵌套列表，几乎必定乱版。
- 表格在移动端阅读体验通常一般，能拆成“图 + 说明文字”就尽量拆。
搜索“markdown 表格转换 excel”的人，本质是需要把管道分隔的文本变成结构化数据。最简单的办法是把表格复制进一个在线 Markdown-to-CSV 工具，或者用 Excel 的分列功能按|拆开。如果常用 VS Code，装一个 Markdown Table 插件可以双向转换。
4.2 LaTeX 数学公式：行内、块级与 GitHub 的差异
Markdown 本身没有数学公式，公式是 LaTeX 语法通过解析器扩展渲染的。Typora、GitHub、知乎、语雀都支持，但支持程度不一样。
行内公式用$...$，块级公式用$$...$$。比如：
- 分数：
$\frac{1}{2}$ - 上下标：
$a^2$、$x_i$ - 求和：
$\sum_{i=1}^{n} i$ - 矩阵：块级公式里写
\begin{matrix} ... \end{matrix}
常用坑有三个。第一，美元符冲突：你要写“成本 $100”这种带金额的句子，$会和公式语法冲突，必须写成\$100。第二，块级公式里中文混排容易产生奇怪的空白，建议公式里只放符号，中文说明放外面。第三，GitHub 的$$块级公式要求独立成段，前后不能有其他行内文字，否则不渲染。所以你在 Typora 里写得爽，推到 GitHub 不显示，多半是这两个平台对“块级”的定义不同。
“markdown 数学公式插件”这个搜索词对应的需求，本质上是给编辑器接入 KaTeX 或 MathJax 渲染器。Typora 内置支持，VS Code 用 Markdown Preview Enhanced 插件也能渲染，不需要额外安装什么神秘工具。
4.3 GitHub Callout：提示块的标准化写法
GitHub 从 2022 年开始支持 Callout 语法，写法是引用块第一行加一个标签：
> [!NOTE] > 需要读者注意的信息。 > [!WARNING] > 可能造成风险的操作提醒。目前支持五种标签：NOTE、TIP、IMPORTANT、WARNING、CAUTION。GitHub 渲染时会变成带颜色的小提示条，比普通引用醒目得多。
这套语法在 GitHub 和部分 VS Code 预览插件里有效，但在语雀、飞书、公众号里不会被识别——它们只会当成普通引用块，内容仍然可读，只是没有彩色标签。所以你放心用，至少不会“裂”。我自己的体验是：写“注意”“警告”这类信息时，用 Callout 或“加粗 + 引用”二选一，看发布平台决定。
4.4 任务列表和其他扩展语法
任务列表写法很简单：
- [ ] 未完成事项 - [x] 已完成事项注意中括号里只能放空格或小写x，括号后面要跟一个空格再接文字。嵌套任务列表和普通嵌套列表的缩进坑一样，子任务也要注意空行。
其余常见扩展还包括：脚注[^1]、目录[TOC]、高亮==text==、上标^text^、下标~text~、删除线~~text~~。但它们的兼容性差异很大。我建议先搞清楚你的发布平台支持什么，再决定用不用。GitHub 原生支持任务列表和删除线，但对高亮、上标、下标的支持是通过 HTML 语义做的，部分笔记软件则完全忽略。
5. 下游消费：Word、Excel、公众号和钉钉里的 Markdown
5.1 Pandoc 转 Word：从命令行到固定模板
Markdown 最常见的“下游”是 Word。最靠谱的工具还是 Pandoc。一行命令：
pandoc input.md -o output.docx标题、列表、表格、代码块基本都能正确转换成 Word 的对应样式。但默认生成的 docx 样式很素，中文字体、标题颜色、页边距都不一定符合公司要求。
解决办法是生成一个自定义 Word 模板。先让 Pandoc 导出默认模板：
pandoc --print-default-data-file reference.docx > custom-reference.docx然后用 Word 打开这个模板，修改各级标题的字体、字号、颜色、行距，再保存。之后每次转换都带模板：
pandoc input.md -o output.docx --reference-doc=custom-reference.docx这样生成的 Word 文档基本就是你要的样子，不用每次手动调样式。注意不同版本 Pandoc 生成模板命令可能有差异，用--print-default-data-file查一下即可。
5.2 表格转 Excel 与 md 转 word 的自动化工作流
有人喜欢用 Coze 这类平台搭“markdown 转 word 工作流”，实话说，对普通文档可行，但一旦文档里塞了复杂表格、数学公式、多层列表，在线工作流的稳定性会明显下降。我的经验是：如果只是个人偶尔转一下，Pandoc 命令行最省心；如果是要处理日报、周报这类重复任务，再把转换脚本封装成一键执行，或者接进 CI。
表格转 Excel 的需求，同理。最简单的场景直接用 Excel 的“数据 → 分列”，把整段表格按|拆开，删掉第一行和分割行即可。复杂一点，用 Python 脚本读 Markdown 表格再写 CSV，稳定性更高。
5.3 公众号 Markdown 格式化的核心是 CSS
公众号编辑器不支持 Markdown。网上各种“公众号 Markdown 格式化工具”的输出物，本质都是一个 HTML 文件：先把 md 渲染成标准 HTML，再把所有样式写进内联style属性，最后复制进公众号编辑器。
这里有个底层约束：微信会过滤<style>标签，所以样式必须写在每个元素的style属性里，不能靠<style>统一声明。
我自己的做法是一套本地 HTML 模板。Markdown 渲染成 HTML 之后，给h1h2h3blockquotepretable分别定义内联样式，比如标题加大加粗、引用块左侧加边框、代码块灰底圆角。粘贴进公众号后样式基本保留。
另外，微信会把代码高亮过滤掉，代码块最多保留灰底和等宽字体，所以别在公众号里指望五颜六色的代码块。图片则是另一种玩法：要么先手动上传到公众号素材库，再在文章里引用素材链接；要么干脆用外链图床，但要注意微信对图片域名偶尔会有加载限制。
5.4 钉钉消息、思维导图和流程图的界面外 Markdown
钉钉机器人发消息支持部分 Markdown：标题、加粗、引用、链接、无序列表、图片（外链）都没问题，但表格和数学公式基本上会退化成纯文本。钉钉预警消息里如果带表格，真正推送出来的效果很难看，经常是|符号一长串。所以我的建议是：钉钉通知消息，格式收敛成“加粗标题 + 关键信息 + 链接”，别放表格。
至于“有道云 markdown 转流程图”“思维导图 markdown”之类的需求，通常是把 Markdown 大纲结构喂给专门工具生成思维导图，或者用类似 Mermaid 这样基于代码块的图语言，在 Markdown 的代码块里写图定义，再由应用渲染成流程图。这属于应用层的扩展能力，不是 Markdown 标准语法。写这类文档时，记得保留一份纯文本版本，不然换到不支持的平台，图就只剩一堆源码。
6. 编辑器、lint 与解析原理：想少踩坑就理解渲染
6.1 我日常使用的 Markdown 编辑器组合
每个编辑器都有它的位置，我按场景分着用。
- Typora：写初稿、看渲染效果、处理图片路径，最顺手。软件是买断制，如果你还在纠结要不要买，我的建议是直接买断，省下的折腾时间比那几十块钱值。不管是 Mac 还是 Windows，一次授权都能用。
- VS Code：处理大量代码仓库文档时首选。配合 preview 插件可以实时渲染，配合 markdownlint 可以做语法检查。
- Obsidian：个人知识库、双链笔记。它对图片附件管理很友好，适合把零散笔记沉淀成长期资料库。
- Sublime Text / 记事本类工具：快速查看 md 源码可以，但不适合写长文。想看渲染效果还是得装插件或者用一个支持预览的编辑器。
选编辑器不用纠结谁最好，而是问自己一个问题：这个文件最终会发布到哪里？如果发布到 GitHub，再用 Typora 预览发现没问题，也一定要去 GitHub 页面再看一眼。编辑器的渲染效果永远不等于目标平台的渲染效果。
6.2 markdownlint：文档也应该有 CI
写代码有 lint，写文档同样应该有 lint。markdownlint 是一套规则集，最常用的包括：
- MD009：行尾空格检查，也就是硬换行用的两个空格。
- MD012：多个连续空行检查。
- MD013：限制行宽，防止一行写太长。
- MD024：同一页面标题重复检查。
- MD025：文档只能有一个顶级标题。
- MD040：代码块必须标注语言。
它既可以作为 VS Code 插件实时提醒，也可以在命令行跑。文档多了以后，靠人肉检查格式是不现实的，把这些规则挂到 CI 里，让机器替你们把关，团队协作时关于格式的争论会大幅度减少。
6.3 从正则到 AST：Markdown 解析器的黑盒不再黑
Markdown 诞生时的实现说白了就是一系列正则替换：把**text**换成<strong>text</strong>，把# heading换成<h1>heading</h1>。一直到今天，这个“正则替换”印象还留存在很多人脑海里，所以遇到“为什么这里没加粗”“为什么这里被当成标题”时，只能靠猜。
现代解析器已经没有这么简单了。markdown-it、remark、marked、python-markdown 这些主流实现，都是先做词法分析，再生成 AST（抽象语法树），最后序列化成 HTML。这也是为什么嵌套列表、转义、行内代码这些场景能处理得更严谨的原因。
理解这一点后，很多问题就不用瞎猜了。行内代码里写**text**不会被加粗，因为解析器按反引号划边界，里面全是代码；标题行内还能加粗，因为块级规则和行内规则是分开处理的；同样的 md 文件在 GitHub 和 Typora 渲染不同，是因为它们用的解析器对细节实现不一样。
如果你想验证一个写法到底是不是通用，可以拿同一段 md 去跑不同的解析器对比输出。Babelmark 这类在线工具就能一次性展示多个解析器的渲染结果，排查跨平台差异时非常好用。
用 Markdown 这么多年，我最大的体会是：别追求一份 md 在所以平台渲染完全一致，那是几乎做不到的。你需要做的是区分“核心内容”和“平台扩展”。一个最小通用子集——标题、列表、引用、代码块、图片、链接、粗斜体、表格——保证内容在任何地方都至少可读；额外的语法糖，比如数学公式、Callout、高亮、目录，只花在真正需要它的平台上。这样写出来的文档，才不会在关键时刻“变脸”。
