我写文档写了快十年Markdown 语法在我这儿属于“十分钟入门、十年里反复踩坑”的东西。上周又翻了一次车同一份 md 文件在 Typora 里排版得干干净净推到 GitLab 上却整段黏在一起两个小时没人发现直到评论区有人问“这段是不是忘了分段”。我后来才发现问题出在一个绝大多数人不会细想的细节——换行。你可以在技术社区里同时搜到 python 语法、shell 语法、正则表达式语法和 Markdown 语法后者看起来最简单但它恰恰因为太简单反而被很多人当成“会了”结果一到多平台发布就原形毕露。这篇东西打算把我这些年用 Markdown 踩过、修过的坑集中整理一下。不打算把语法表从头抄一遍重点讲那些在不同平台、不同工具之间会“变脸”的细节以及我长期验证下来比较稳的写法。适合写 README、维护团队文档、发公众号文章、做个人笔记的朋友参考。1. 换行这件小事足以让你在 Git 平台和编辑器里看到两篇“文章”1.1 三种换行写法分清楚就不再抓狂Markdown 里“换行”至少有三种含义很多人混为一谈。第一种是段落分隔两段文字之间空一行。渲染结果是两个独立的段落段与段之间有明显的垂直间距。这是最推荐的方式语义最清晰几乎所有解析器都认。第二种是硬换行在一行末尾敲两个空格再回车。渲染结果是同一个段落内部折行行尾产生一个br。这在诗歌、地址、代码行内注释等需要精确换行的场景下有用。第三种是软换行直接按一次回车不加任何东西。大多数解析器会把它当成一个普通空格意思就是“你虽然换行了但渲染时文本还是连在一起的”。还有一部分实现支持行尾加反斜杠\来换行这是 Markdown Extra 和 GFMGitHub 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 srcxxx.png width400。这种写法不是标准 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_{i1}^{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、公众号和钉钉里的 Markdown5.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-doccustom-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 从正则到 ASTMarkdown 解析器的黑盒不再黑Markdown 诞生时的实现说白了就是一系列正则替换把**text**换成strongtext/strong把# heading换成h1heading/h1。一直到今天这个“正则替换”印象还留存在很多人脑海里所以遇到“为什么这里没加粗”“为什么这里被当成标题”时只能靠猜。现代解析器已经没有这么简单了。markdown-it、remark、marked、python-markdown 这些主流实现都是先做词法分析再生成 AST抽象语法树最后序列化成 HTML。这也是为什么嵌套列表、转义、行内代码这些场景能处理得更严谨的原因。理解这一点后很多问题就不用瞎猜了。行内代码里写**text**不会被加粗因为解析器按反引号划边界里面全是代码标题行内还能加粗因为块级规则和行内规则是分开处理的同样的 md 文件在 GitHub 和 Typora 渲染不同是因为它们用的解析器对细节实现不一样。如果你想验证一个写法到底是不是通用可以拿同一段 md 去跑不同的解析器对比输出。Babelmark 这类在线工具就能一次性展示多个解析器的渲染结果排查跨平台差异时非常好用。用 Markdown 这么多年我最大的体会是别追求一份 md 在所以平台渲染完全一致那是几乎做不到的。你需要做的是区分“核心内容”和“平台扩展”。一个最小通用子集——标题、列表、引用、代码块、图片、链接、粗斜体、表格——保证内容在任何地方都至少可读额外的语法糖比如数学公式、Callout、高亮、目录只花在真正需要它的平台上。这样写出来的文档才不会在关键时刻“变脸”。