Markdown 扩展语法完全指南：GFM、Pandoc、MultiMarkdown 对比与实战

Markdown 扩展语法是什么？为什么需要它？

如果你用过一段时间的 Markdown，大概率遇到过这样的困惑：明明在 GitHub 上能正常渲染的表格，换到某个博客平台就变成了一堆竖线和短横线。这是因为你用到了 Markdown 扩展语法（markdown extensions）。

John Gruber 在 2004 年设计 Markdown 时，定义了一套相当精简的基础语法——标题、列表、链接、图片、代码、粗体、斜体，差不多就这些。他当年的目标是让纯文本"易读易写"，而不是做一个全功能的排版系统。

但现实中写文档的需求远不止于此。你需要表格来展示数据，需要脚注来标注引用来源，需要任务列表来追踪进度，需要数学公式来写学术笔记。这些功能统统不在原始 Markdown 规范里。

于是各路人马开始各自扩展。GitHub 加了表格和任务列表，Pandoc 加了脚注和数学公式，MultiMarkdown 加了引用和元数据……这就形成了今天我们看到的"Markdown 扩展语法"生态——一个百花齐放但也多少有点混乱的局面。

说实话，理解了这个背景，很多平台之间渲染结果不一致的问题就能解释通了。不是你写错了，而是它们支持的扩展集合不一样。

四大主流 Markdown 扩展变体

目前影响最大的 Markdown 变体（也叫"方言"或"flavor"）有四个，它们构成了扩展语法的主要版图。

CommonMark：只管标准，不扩展现

CommonMark 项目始于 2014 年，目的是解决原始 Markdown 规范中的歧义问题。它做了一件很重要的事：把基础 Markdown 的行为用精确的规范和测试套件定义清楚。根据 CommonMark 官方规范，CommonMark 本身不包含任何扩展——没有表格，没有脚注，没有删除线。

但 CommonMark 的各种解析器实现（比如 JavaScript 的 markdown-it、PHP 的 league/commonmark）通常提供了可选的扩展机制，可以在 CommonMark 基础上开启 GFM 表格、删除线等功能。换句话说，CommonMark 提供了标准化的地基，扩展是你在上面自己加的楼层。

GFM（GitHub Flavored Markdown）：用得最广泛的扩展集

GFM 是 GitHub 基于 CommonMark 定义的扩展规范。根据 GitHub 官方文档，GFM 是 CommonMark 的严格超集——每个合法的 CommonMark 文档在 GFM 中都合法。

GFM 在 CommonMark 基础上加了四个官方扩展：

扩展语法示例用途
表格| 列1 | 列2 |结构化数据展示
删除线~~删除的文字~~标记废弃内容
自动链接直接写 URL 自动变链接免去手动加 <> 的麻烦
任务列表- [ ] 待办 / - [x] 已完成项目管理和待办追踪

我个人的感觉是，GFM 这四个扩展选得非常精准——覆盖了开发者在 GitHub 上写 README 和文档时最常用的功能。如果你写的内容主要发在 GitHub 或 GitLab 上，GFM 扩展基本就够用了。

Pandoc Markdown：扩展最丰富的专业级方案

Pandoc 是学术写作和文档转换领域的瑞士军刀。它定义了自己的 Markdown 方言，提供了极其丰富的扩展库。根据 Pandoc 官方手册，你可以通过 +扩展名 或 -扩展名 的方式精细控制每个扩展的开关。

一些典型的 Pandoc 扩展：

pandoc -f commonmark+table_captions+footnotes -t html input.md

# 启用 YAML 元数据块和围栏代码块
pandoc -f markdown+yaml_metadata_block+fenced_code_blocks -t pdf input.md

Pandoc 支持的扩展涵盖了几十种功能——脚注、定义列表、上标下标、数学公式、引用文献（citations）、YAML 元数据块、围栏 div（fenced divs）、行内属性（inline attributes）等等。它甚至提供了兼容 MultiMarkdown 语法的扩展选项。

对了，有一点值得注意：Pandoc 可以在多种 Markdown 模式下工作（markdown、commonmark、gfm、commonmark_x），每种模式可用的扩展集合略有不同。具体可以查阅 Pandoc 手册的"Non-default extensions"章节。

MultiMarkdown：学术写作的先驱

MultiMarkdown 由 Fletcher Penney 创建，是最早对原始 Markdown 进行大幅扩展的方案之一，主要面向学术和技术文档写作。它添加了脚注、表格、引用（citations）、元数据、交叉引用等出版级别的功能。

MultiMarkdown 有自己的解析器，不是基于 CommonMark 的。它的语法规则跟 GFM 和 Pandoc 有重叠但也有差异。目前 MultiMarkdown 的使用范围相对较小，很多 MultiMarkdown 的功能都可以通过 Pandoc 的兼容扩展来实现。除非你有遗留的 MultiMarkdown 文档，否则一般建议用 Pandoc 作为替代。

Markdown Extra：PHP 生态的重要扩展

除了上面四大变体，还有一个绕不开的名字是 PHP Markdown Extra。它是 Michel Fortin 在 PHP Markdown 库基础上添加的扩展集，引入了表格、定义列表、脚注、缩写（abbreviations）、代码块围栏等功能。

虽然 PHP Markdown Extra 本身的影响力在下降，但它的很多语法设计被其他解析器借鉴了。比如 markdown-it 的 markdown-it-deflist 插件就沿用了类似的定义列表语法。在讨论 markdown extra 的时候，基本上是在讨论这一脉的扩展传统。

各扩展功能在各变体中的支持情况

这个表格是我根据 Markdown Guide、Pandoc 手册 和 GitHub 文档 交叉整理的，列出了常见的扩展功能在各大变体中的可用性：

扩展功能语法概要GFMPandocMultiMarkdownCommonMark 解析器
表格| 列1 | 列2 |✅ 原生✅✅多数支持（作为插件）
删除线~~文字~~✅ 原生✅❌多数支持
任务列表- [ ] / - [x]✅ 原生✅❌部分支持
脚注[^1]❌✅✅需插件
定义列表术语 : 定义❌✅✅需插件
上标/下标H~2~O / X^2^❌✅✅需插件
数学公式$E=mc^2$❌✅✅需插件
自动链接裸 URL 自动链接✅ 原生✅✅多数支持
YAML 元数据--- 包裹的 front matter❌✅✅需插件
引用文献[@key]❌✅✅需插件
围栏代码块```lang✅✅✅多数支持
语法高亮围栏代码块指定语言✅✅✅需配置
标题 ID{#custom-id}❌✅✅需插件
高亮标记==高亮==❌✅❌需插件

说明：表格中的"多数支持"指 CommonMark 解析器通常提供对应的可选扩展插件。"需插件"表示解析器本身不内置，但可以通过社区插件实现。"❌"表示该变体不支持此功能。

说实话，从这个表可以看出一个很清楚的趋势：GFM 覆盖面窄但用得最广，Pandoc 覆盖面最广但需要配置。 你对扩展功能的需求越复杂，就越可能需要 Pandoc。

实测：扩展语法在不同平台上的兼容性

光看规范文档有时候不够直观，我实际测试了几个常见的扩展语法在主流平台上的渲染效果。

GitHub / GitLab

GitHub 和 GitLab 都支持 GFM，所以表格、删除线、任务列表、自动链接这些都没问题。但 GitHub 的 Markdown 渲染不支持脚注——你在 GitHub README 里写 [^1]，它不会被渲染为脚注链接，只会原样显示。这一点让不少从学术写作转到 GitHub 的朋友踩了坑。

GitLab 的扩展支持比 GitHub 稍宽，支持脚注和数学公式（通过 KaTeX）。

VS Code（内置预览 + Markdown Preview Enhanced 插件）

VS Code 内置的 Markdown 预览支持 GFM 扩展（表格、删除线、任务列表）。如果安装了 "Markdown Preview Enhanced" 插件，还额外支持脚注、数学公式（KaTeX/MathJax）、Mermaid 图表、目录（TOC）等更多扩展。

我的建议是，如果你在 VS Code 里写 Markdown，装一个 Markdown Preview Enhanced 会省很多事。

Typora

Typora 对扩展语法的支持相当全面——表格、脚注、数学公式、上标下标、高亮、目录都支持。它底层用的是不同的解析器，基本上把 GFM 扩展和 Pandoc 的常用扩展都包进去了。如果你想要一个"开箱即用支持最多扩展"的桌面编辑器，Typora 是个不错的选择。

静态站点生成器（Hugo / Jekyll）

Hugo 默认支持 GFM 扩展，也支持 Goldmark 解析器的各种扩展选项。Jekyll 使用 kramdown 作为默认解析器，支持表格、脚注、定义列表等。两者都可以通过配置文件开启或关闭特定的扩展。

有一次我用 Hugo 写博客，默认配置下围栏代码块里的数学公式死活渲染不出来，排查了半天才发现是 Goldmark 的扩展没有在 hugo.toml 里显式开启。这种"默认不开"的设计在静态站点工具里很常见，遇到功能不生效的时候，先检查配置。

怎么选择适合自己的 Markdown 变体？

选择哪个 Markdown 变体，主要取决于你的使用场景：

场景一：写 GitHub README 或项目文档→ 直接用 GFM 就好。GitHub 只支持 GFM 扩展，你用了 Pandoc 的脚注语法也不会被渲染。专注于表格、任务列表、代码块这三个核心功能。

场景二：写博客或个人笔记→ 推荐 Typora 或 VS Code + Markdown Preview Enhanced。它们的扩展支持全面，大部分扩展语法开箱即用。如果你的博客用 Hugo 或 Jekyll，记得对照构建工具的文档确认支持哪些扩展。

场景三：写学术论文或技术书籍→ Pandoc 是首选。它的脚注、引用文献、数学公式、YAML 元数据、交叉引用这些功能是其他变体难以匹敌的。配合 LaTeX 模板可以输出高质量的 PDF。

场景四：需要最大兼容性（多平台发布）→ 坚守 CommonMark 基础语法 + GFM 扩展。这套组合在几乎所有平台上都能正确渲染。避免使用脚注、定义列表、上标下标等"高级"扩展，或者准备好多个版本的文档。

常见问题

CommonMark 和 GFM 是什么关系？

GFM 是 CommonMark 的严格超集。你可以理解为 CommonMark 是地基，GFM 在上面盖了四间房（表格、删除线、自动链接、任务列表）。所有合法的 CommonMark 文档在 GFM 中也合法，反过来则不一定。

Markdown 扩展语法会继续分裂吗？

这个问题在 CommonMark 社区 已经讨论了很多年。目前看来，扩展语法不太可能统一到一个标准下——不同使用场景的需求差异太大了。更现实的做法是：CommonMark 继续作为稳定的核心标准，各变体在它之上按需扩展。GitHub 的 GFM 规范化工作（将 GFM 也做了正式规范定义）是一个积极信号，至少最常用的那几个扩展有了清晰的定义。

Pandoc 的扩展这么多，该怎么入门？

不需要一次学完所有扩展。我的经验是从这三个开始：

  1. yaml_metadata_block — 用 YAML 管理文档元数据
  2. footnotes — 写长文档必备
  3. fenced_code_blocks — 比缩进式代码块好用得多

其他扩展等你遇到了具体需求再去查 Pandoc 手册就行。

在 GitHub 上能用脚注吗？

不能。截至 2026 年，GitHub 的 Markdown 渲染器不支持脚注语法。如果你需要在 GitHub 文档里加注，可以用 HTML 超链接跳转到页面底部的手动"注"章节，或者用 <sup> 标签做上标标记。

markdown-it、marked、showdown 这些解析器有什么区别？

它们都是 JavaScript 的 Markdown 解析器，区别在于对扩展的支持方式：

  • markdown-it — 严格遵循 CommonMark 规范，通过插件添加扩展，设计最模块化
  • marked — 速度最快，默认支持 GFM 扩展，但扩展机制不如 markdown-it 灵活
  • showdown — 也支持 GFM，更适合浏览器端使用

如果你在做一个 Web 应用需要集成 Markdown 解析，markdown-it 的插件生态是三者中最丰富的。

参考来源：