Markdown扩展语法指南：表格、脚注、任务列表与删除线

Markdown扩展语法是指John Gruber于2004年发布原始规范之后新增的一系列格式元素。 2004年的规范只定义了11种基本元素，完全没有包含表格、脚注、任务列表和删除线。后来的项目填补了这些空白：MultiMarkdown在2005年带来了表格和脚注，Pandoc于2006年问世并拥有所有处理器中最庞大的扩展集，CommonMark在2014年将核心语法标准化并为扩展留出空间，GitHub则在2017年发布了GFM规范。本页的每个元素都能在编辑器的实时预览中渲染，粘贴5秒钟就能知道目标应用是否支持。

支持对照表

没有任何应用支持全部12种扩展元素，因此发布前请先确认目标平台的支持情况。 4个最常见的目标平台差异明显：

一条实用的经验法则：markdown表格、围栏代码块、markdown删除线和markdown任务列表几乎在所有平台都能渲染。定义列表、高亮、下标和上标则是最容易失效的4种元素。

表格

Markdown表格用竖线字符分隔列，并用3个或更多连字符组成的分隔线标记表头行。 在大多数解析器中外侧竖线是可选的，但保留它们能提高兼容性，建议保留。

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

分隔行中的冒号控制对齐方式。:---使列左对齐，:---:使其居中，---:使其右对齐。解析器会把对齐方式应用到该列的每个单元格。各列的连字符数量不必一致。要在单元格内显示竖线字符本身，请写HTML实体|；GitHub也接受反斜杠转义\|。单元格支持粗体、行内代码等行内格式，但绝不支持列表、标题等块级元素。

MultiMarkdown在2005年引入了这一语法，GFM于2017年采纳。GitHub、GitLab、Obsidian和Pandoc都能渲染markdown表格，Discord不支持。

围栏代码块

围栏代码块以3个反引号开始和结束，无需缩进，这一点不同于2004年规范中的4空格代码块。 在大多数解析器中，3个波浪号可作为替代围栏。

```python
def total(items):
    return sum(items)
```

在开头围栏后紧跟语言标识符即可开启语法高亮。highlight.js是许多网页渲染器背后的库，内置约200种语言的定义，常见标识符包括python、js、json、bash和sql。要在代码块中展示另一个代码块，把外层围栏改为4个反引号。

它的支持范围是所有扩展元素中最广的。GitHub、Obsidian、Discord和Pandoc都能渲染围栏代码块，且4者都支持语言高亮。

脚注

Markdown脚注由2部分组成：正文中的引用标记，写作[^1]；以及可放在文件任意位置的定义，写作[^1]: 后接注释内容。 渲染器会把所有定义汇总到页面底部，并在每对标记之间建立双向链接。

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

标识符既可以是数字也可以是单词，[^note]的行为与[^1]完全相同，因为输出编号遵循文档顺序而非标签本身。当额外段落在定义下方缩进4个空格时，一条脚注可以容纳多个段落。

MultiMarkdown早在2005年就支持了脚注，Pandoc和Obsidian提供完整支持，GitHub于2021年加入了脚注渲染。Discord不支持markdown脚注。

标题ID

自定义标题ID位于标题行末尾的花括号中，## Refund Policy {#refunds}会输出带有id="refunds"的HTML h2元素。 这个ID成为链接和CSS可用的稳定锚点。

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

这种链接就是标准的Markdown链接，以井号加ID作为目标。在完整页面URL后追加#refunds，外部页面也能跳转到同一位置。

Pandoc和PHP Markdown Extra能解析花括号形式。GitHub会忽略它，但会根据标题文字自动生成ID，因此指向#refund-policy的链接在GitHub上仍然有效。Obsidian使用自己的[[Note#Heading]]模式来链接标题。Discord能在消息中渲染标题，但没有锚点系统。

定义列表

定义列表把一个术语与1条或多条定义配对：术语单独占一行，每条定义从下一行开始，以冒号加一个空格开头。

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

输出是真正的<dl>元素，包含<dt>和<dd>子元素，这对词汇表和屏幕阅读器都很重要。连续堆叠的冒号行可以为同一术语提供多条定义。

支持范围很窄。PHP Markdown Extra定义了这一语法，Pandoc和MultiMarkdown都能解析。GitHub和Obsidian会把冒号行显示为纯文本，Discord同样如此。在GitHub上，直接写<dl>HTML是可靠的替代方案。

删除线

Markdown删除线在文字两侧各加2个波浪号，like this会渲染为划掉的文字。 该元素来自GFM，HTML输出为<del>元素。

~~Ship v2 on Friday.~~ Moved to Monday.

GitHub也接受每侧只加1个波浪号。为了可移植性请坚持用2个，因为单波浪号在Pandoc中表示下标，1个字符的差异就会改变含义。

支持几乎是通用的。GitHub、Obsidian、Discord和Pandoc都能渲染2波浪号删除线。

任务列表

Markdown任务列表项以普通列表项开头，再加上方括号：- [ ] 表示未完成任务，- [x] 表示已完成任务。 空方括号内的空格是必需的。

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

GitHub在2013年引入了这一语法，并让复选框在issue和pull request中可以交互，点击即可更新底层的Markdown。GitHub还会统计任务数量，issue会显示诸如“2 of 3 tasks”的进度。Obsidian在阅读视图中渲染可点击的复选框，Pandoc把任务列表转换为HTML复选框。Discord则把方括号按原样显示为字符。

Emoji

Emoji进入Markdown文件有2种方式：直接粘贴Unicode字符，或在支持短代码展开的应用中输入:rocket: 这样的短代码。 粘贴的emoji能在任何UTF-8文件中保留，因此🎯在短代码失效的地方也能显示。

Release day :tada: went live at 9 am.

短代码是用2个冒号包住emoji名称。GitHub能展开大约1,800个短代码，Discord能展开自己的短代码集合以及各服务器的自定义emoji。Obsidian需要社区插件才能使用短代码，但能原生显示粘贴的emoji；Pandoc只有开启emoji扩展后才展开短代码。各平台的名称并不一致，在GitHub可用的短代码在其他任何地方都不保证可用。

高亮

高亮在文字两侧各加2个等号，==like this==会渲染出类似荧光笔的背景，通常是黄色。 HTML输出为<mark>元素。

The deadline moved to ==14 March== at noon.

这是可移植性最差的扩展元素之一。Obsidian默认支持渲染，Pandoc在启用mark扩展后可以解析，该扩展自2023年发布的Pandoc 3.0起提供。GitHub和Discord会原样显示等号。当语法失效时，<mark>标签在任何放行HTML的渲染器中都有效，包括GitHub的readme文件。

下标与上标

下标在字符两侧各加1个波浪号，如H2O；上标在两侧各加1个插入符号，如x^2^。 两种形式都来自Pandoc的扩展集，而非任何常见的网页flavor。

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

Pandoc把它们转换为<sub>和<sup>元素。GitHub和Obsidian会忽略波浪号和插入符号形式，但会放行HTML标签，因此H₂O在两者中都有效。Discord两种都不支持。注意波浪号冲突：支持单波浪号删除线的应用会把你的下标划掉，而不是把它变成下标。

URL自动链接

URL自动链接把https://example.com这样的裸地址直接变成可点击的链接，无需方括号语法。 GFM在2017年的规范中把这一行为正式定义为autolink扩展。

Full docs at https://example.com/docs

GitHub和Discord会把裸URL转为链接，Obsidian在阅读视图中也是如此。Pandoc默认关闭该行为，除非启用autolink_bare_uris扩展。要阻止URL变成链接，请用反引号把它包起来；行内代码永远不会被转成链接，因此https://example.com在配置示例和占位域名中会保持纯文本。

常见问题

扩展语法属于官方Markdown吗？

不属于。2004年的规范只定义了11种基本元素，本页的每个元素都来自后来的flavor和处理器。 Markdown没有官方管理机构，这正是各应用支持情况不同的原因。

哪种Markdown flavor支持的扩展语法最多？

Pandoc支持的范围最广，拥有30多个可选语法扩展，能解析本页全部12种元素。 对网页发布而言，GFM是更实用的目标，因为GitHub、GitLab和大多数现代编辑器都遵循它。

为什么表格在GitHub能渲染，在Discord却不行？

Discord实现的是为聊天设计的极简Markdown子集，不包含表格、脚注、任务列表和定义列表。 它的子集涵盖粗体、斜体、删除线、标题和围栏代码块。面向Discord的内容应只使用这5种元素。

发布前如何测试扩展语法？

把元素粘贴到在线编辑器的实时预览中，它能在1秒内渲染GFM加脚注。 对于其他任何目标平台，把2行示例直接粘贴到目标应用里测试；支持对照表已覆盖4个最常见的场景。