4.2 GFM：事实上的互联网标准

4.2 GFM：事实上的互联网标准

GFM（GitHub Flavored Markdown）是代码托管平台在 CommonMark 之上加的一组扩展：表格、任务列表、删除线、自动链接、更严的代码围栏。因为这家平台的巨大影响力，GFM 已成为"如果你不知道对方支持什么，就按 GFM 写"的默认选择。

GFM 加了什么

逐一对照我们在第 2 章练过的语法：

| 列一 | 列二 |          ← 表格
| --- | --- |
| 数据 | 数据 |

~~过时的说法~~              ← 删除线

- [x] 已完成事项            ← 任务列表

https://example.com 自动成链  ← 自动链接
​

还有两项"收紧"而非"扩展"的规定值得知道：

1. 换行即换行：GFM 把源码里的单个换行渲染为 HTML 换行——这改变了 CommonMark"换行合并"的行为。所以你在平台 README 里敲回车就能换行，别处却要行尾两空格。
2. 过滤不安全 HTML：script、iframe 等直接剥离（呼应 3.3 节）。

GFM 之外但常被误认为 GFM 的

数学公式（$...$）、脚注（[^1]）、Mermaid 图在标准 GFM 规范里并不存在，它们是该平台产品层的附加渲染能力，或其它方言的功能。判断依据很简单：GFM 官方规范文档里列了哪些就是哪些，产品额外支持的属于"平台扩展"。

为什么它成了事实标准

一方面是用户基数：全球最大代码托管平台的 README、issue、评论全都吃 GFM，教程作者写文档天然以它为准。另一方面是工程外溢：解析它的库被大量第三方产品复用，很多笔记软件、知识库的"Markdown 支持"实际是"GFM 支持"。

这带来一个实用推论：面向互联网发布的文档，按 GFM 写是安全赌注；表格、任务列表、删除线几乎不会让你失望。

CommonMark 与 GFM 的检查对照表

⚠️ 常见坑："本地编辑器渲染正常、传到严格 CommonMark 环境表格变竖线"。这不是 bug——目标环境不支持表格。多平台文档要么去表格化，要么接受降级显示。

跨方言移植测试：五分钟体检法

判断一份文档在目标平台的表现，不必通读规范，做一个五分钟移植测试就够。挑出文档里每种语法的一个代表样本，拼成一小页"语法体检样张"，先在源平台渲染确认正常，再贴到目标平台：

## 语法体检样张

| 语法 | 样本 | 结果 |
| --- | --- | --- |
| 表格 | 本行即是 | 记录是否成表 |
| 任务 | - [ ] 记录是否可勾选 | |
| 删除 | ~~样本~~ | 记录是否有横线 |

第一行
第二行（记录是否被合并）

- [ ] 任务项样本
~~删除线样本~~
[链接](https://example.com) 与 https://auto.link.example.com
​

样张在目标平台渲染后逐项记录：正常、降级（表格变竖线文字）、消失（任务列表变普通列表）还是错乱（换行全部丢失）。这张记录表就是该平台对这份文档的"方言兼容报告"——比读任何文档都准确，因为产品层的附加能力（数学、图表）经常与宣传有出入，实测才是唯一可靠的口径。样张本身值得存进团队仓库，新平台接入、现有平台升级后，重新贴一遍即可回归。

体检发现的差异按成本处理：换行差异用显式换行写法根治（成本最低，建议所有跨平台文档直接采用）；表格降级视目标平台权重决定去留；任务列表消失可退化为普通列表加"已完成"文字前缀。原则始终是：让文档迁就读者的平台，而不是要求读者的平台迁就文档。

本节要点回顾

• GFM = CommonMark + 表格/任务列表/删除线/自动链接 + 换行语义收紧。
• 互联网发布的默认赌注：按 GFM 写，兼容面最大。
• 数学/脚注/图表不是 GFM 规范内容，属平台层能力，用前确认。
• 换行行为差异是跨平台排版错乱的隐形元凶之一。

GFM 表格与任务列表的边界细节

即便同为 GFM，两个高频扩展仍有边界细节值得单独记。表格方面，GFM 规范明确单元格不能包含普通换行，想换行只能用 <br>——这就是第 2 章"单元格换行"一节说"查平台再上"的规范出处；管道表的单行长度也没有上限，但多数渲染器对超长行做软折行处理，视觉效果因主题而异。任务列表方面，GFM 只认列表标记后的 [ ] 与 [x]（小写），[X] 大写虽被 GitHub 网页端接受，却不在规范文本内——按规范写字面量，平台接受超集，永远不会错。

删除线还有一个容易被误解的细节：GFM 的删除线要求双波浪线，单波浪 ~文字~ 不生效（这正是上标方言 ~文字~ 能与之共存的原因）；波浪定界符与内容之间不能有空格，~~ 文字 ~~ 原样输出。把这些细节攒成一张"扩展语法规范字面量"小抄贴在团队 wiki，新人头三个月的方言类疑问能消掉一大半——多数人不是不懂概念，只是把各平台的宽容当成了规范本身。

用一份文档验证 GFM 覆盖面

动手做一次覆盖面验证：写一份包含表格、任务列表、删除线、自动链接、围栏代码块的测试文档，分别贴到 GitHub 仓库、公司 GitLab、主流技术社区的编辑器里各渲染一遍。你会得到一张实感的矩阵——多数平台五项全过，个别平台任务列表不交互、自动链接不生效。这张自测矩阵的意义在于：它把你将来要用的每个平台的 GFM 取舍变成亲眼见过的事实，而非文档里的二手描述。写跨平台内容时矩阵里任何"某平台不支持"的项，要么换写法要么进白名单管控——多平台策略的决策依据，从此来自你自己的验证数据。

任务列表的回写机制与限制

GFM 任务列表在 GitHub 上最容易被误解的一点是回写的边界：勾选只发生在渲染界面上，且只对仓库内文件生效——API 拉取的 Markdown 源码里勾选状态就是字面的 [x]，没有独立的数据库状态。由此推出两个实用结论：其一，把勾选状态当"已核实的进度"可信，因为它必然对应一次真实编辑（人或提交）；其二，凡是不走渲染界面的消费路径（邮件通知、RSS、爬虫），任务列表退化为普通列表，信息不丢但交互消失——设计流程时别把"必须勾选"这一环放在非渲染通道里。