Markdown 脚注怎么写，哪里能渲染

Markdown 写作约 3 分钟

脚注由两部分组成，正文里写标记 [^1]，另起一行写定义 [^1]: 脚注内容，渲染时定义会被收集到页面底部，并按标记出现的顺序编号。脚注不属于 CommonMark，能不能用要看具体的软件，妙言 V4.5.0、GitHub 和 Pandoc 都能渲染，有些 Markdown 处理器则会把方括号原样显示出来。

写法

两部分用同一个标签对应起来。

Markdown 没有官方的图片尺寸语法。[^size] 多数软件会接受 HTML。[^html]

[^size]: CommonMark 规范把图片定义为带描述的链接。
[^html]: `<img width>` 的写法见图片那篇。

标记 [^size] 紧跟在要解释的词或标点后面，定义可以放在任何独占一行的位置，常见的做法是放在段落下面或整篇笔记末尾。GitHub 的文档明确说过，定义写在哪里不会影响脚注渲染的位置，所以紧挨着引用写也会出现在页面底部。

标签只是用来把两边连起来的键，数字可以，[^size] 这样的单词也可以。Pandoc 手册规定标识符里不能有空格、制表符、换行以及 ^、[、]，输出时脚注一律按顺序编号，和你写的标签无关。脚注超过五六条以后，用有含义的标签会省事很多，中间插一条也不用重新排号。

比较长的脚注

脚注可以跨多行。GitHub 的语法页说，要在脚注里换行，行尾加两个空格；Pandoc 走得更远，脚注的后续段落要缩进，手册把它类比为多段落的列表项。

[^longnote]: 脚注的第一段。

    第二段，缩进四个空格。

多段落写法是 Pandoc 文档里的，GitHub 那页没有讲。妙言 V4.5.0 用的 cmark-gfm 会把缩进的第二段留在同一条脚注里，不缩进的段落回到正文。换别的渲染器时，在大篇幅依赖它之前先试一条长脚注。Pandoc 还有行内脚注 ^[脚注内容]，不需要标签和单独的定义，但它是 Pandoc 的扩展，流程里没有 Pandoc 就用不上。

各处的支持情况

位置 脚注
CommonMark 规范 没有定义，规范里只提到有些实现自己加了脚注
GitHub 的 .md 文件、issue 和 PR 支持，定义渲染在底部
GitHub wiki 按 GitHub 语法页的说法不支持
Pandoc 支持，含缩进的多段落脚注和行内脚注
妙言 V4.5.0 预览和基于预览渲染的导出里支持，见下文

最常见的坑是把笔记在这些环境之间搬。为妙言或 Pandoc 写的笔记贴进 GitHub wiki，[^1] 会原样留在正文里。

妙言 V4.5.0 的做法

妙言用 cmark-gfm 的 Swift 包渲染 Markdown。V4.5.0 的 Business/Markdown.swift 里，解析器创建时打开了脚注选项，然后按名字挂上四个语法扩展，table、footnotes、strikethrough 和 tasklist，所以脚注是默认开启的，没有设置项。解析结果以允许原始 HTML 的方式转成 HTML，再交给网页视图显示，HTML 导出和 PDF 导出也建立在同一套渲染上，预览里能用的脚注在导出里同样能用。cmark-gfm 会把每个标记变成指向脚注的上标数字，把定义收进文末 footnotes 区块里的编号列表，每条后面带一个返回正文的链接。在预览里点标记会滚动到对应的脚注。

应用自带的语法指南里也有「Footnotes」一节，带五条定义，可以照着复制。预览资源包里没有脚注专用的样式，外观就是页面的默认样式。

幻灯片模式是例外。这时妙言把笔记交给 reveal.js 的 Markdown 插件，插件用的是 marked 而不是 cmark-gfm，V4.5.0 的插件源码里没有脚注处理，所以不要指望脚注在幻灯片里渲染。要在幻灯片里放出处，可以把来源写成观点下面的小字，做法见 Markdown 转幻灯片。

脚注没有渲染时

  • 方括号原样显示。 处理器没有脚注扩展，或者你在 GitHub wiki 里，对照上面的表格。
  • 定义被当成普通段落。 多半是定义没有从行首开始，或者标签和标记差了一个字符。Pandoc 把 [^Size] 和 [^size] 当成两个键，妙言用的 cmark-gfm 不分大小写，复制标签在两边都稳。
  • 长脚注后面的正文被吞掉。 Pandoc 里不缩进的段落会结束脚注，下一段前留一个空行，缩进保持一致。
  • 编号和标签对不上。 Pandoc 不管标签写什么都按顺序编号，[^7] 可能显示成 1，标签只是键，不是最终显示的数字。

导出 PDF 时妙言打印的是预览，所以脚注会出现在文末的列表里；想换一种版式，可以改走 Pandoc，流程见 在 Mac 上把 Markdown 转成 PDF。其他依赖具体软件的语法，比如提示块和公式，可以看 Markdown 语法速查与 GFM 差异。

常见问题

GitHub 的 README 支持脚注吗？

支持。GitHub 语法页记录了 [^1] 标记加定义的写法，渲染在文件底部，同时写明 wiki 不支持脚注。

脚注能放进表格单元格或列表项里吗？

Pandoc 手册说脚注定义可以出现在任何地方，只是不能在列表、引用块、表格这类块元素内部。标记本身是行内文本，妙言 V4.5.0 里写在表格单元格中的标记会正常渲染成脚注，换别的渲染器要先看结果再依赖它。

一篇笔记的脚注数量有上限吗？

GitHub 和 Pandoc 的文档以及妙言的解析器配置里都没有写上限，条数多时用有含义的标签更好维护。