Markdown 脚注语法完全指南

Markdown脚注

脚注（footnote）这个东西，写论文的时候特别常见——就是正文里冒出一个小小的上标数字 ¹，点一下跳到页面底部看补充说明。如果你用 Markdown 写技术文档或者学术文章，大概率会用到这个功能。

这篇文章我就把自己用 markdown footnote 的经验整理一下，从最简单的用法讲到一些容易踩的坑。

什么是 Markdown 脚注

Markdown 脚注就是在正文里插一个上标标记，读者点一下就能跳到页面底部看详细内容，跟 Wikipedia 里那种引用标注差不多。

顺便提一句，如果你是想在文档里加"不会显示出来"的隐藏备注，那应该用 Markdown 注释，脚注是会显示的，别搞混了。

Markdown 脚注基础语法

Markdown 脚注分为两部分：引用标记（放在正文中）和脚注定义（放在文档中任意位置）。

引用式脚注

这是最常用、支持最广泛的 markdown footnote syntax：

这是一段正文，这里需要添加脚注。[^1]

[^1]: 这是脚注的具体内容。

渲染效果：

这是一段正文，这里需要添加脚注。¹

¹ 这是脚注的具体内容。

语法要点：

  • 正文中用 [^标签] 标记脚注位置
  • 文档任意位置用 [^标签]: 脚注内容 定义脚注
  • 标签可以是数字（1、2）或单词（note、source）
  • 渲染器会自动按出现顺序编号，所以标签名不影响最终显示的编号

这里有个我自己踩过的坑：标签名必须和正文里的引用一模一样。有一次我正文写的是 [^note1]，定义时手滑写成了 [^note-1]，就多了个连字符，结果脚注死活不显示。排查了好久才发现是这个小问题。

行内式脚注

Pandoc 和部分解析器支持更简洁的行内写法：

这是一段话。^[这是行内脚注的内容，不需要单独定义。]

行内式脚注不需要在文档其他位置定义，脚注内容直接写在 ^[...] 中。这种写法适合简短的脚注。

需要注意的是，行内式脚注 ^[...] 只有 Pandoc 和少数编辑器认。GitHub、GitLab 这些主流平台都不吃这套。所以如果你要跨平台使用，老老实实用引用式 [^标签] 就好。

多段落脚注

当脚注内容较长，需要分成多个段落时，后续段落需要缩进 4 个空格：

这里有一个多段落脚注。[^long]

[^long]: 这是脚注的第一段内容。
    这是同一段脚注的第二段，前面有 4 个空格的缩进。

    第三段也需要 4 个空格缩进。脚注内还可以使用 **加粗** 和 [链接](https://example.com) 等 Markdown 格式。

关键规则：

  • 脚注定义后的第一行紧跟冒号后写
  • 后续每个段落前缩进 4 个空格（不是 Tab）
  • 段落之间用空行分隔，空行也需要缩进

这里我踩过一个坑：在 GitHub 上用 Tab 缩进，结果所有内容被挤成了一段。换成 4 个空格就好了。不过 Obsidian 里倒是 Tab 和空格都行，只能说各平台处理方式不一样。反正为了不出问题，统一用 4 个空格最稳。

脚注标识符命名规则

脚注标识符（标签）的命名比较灵活：

写法示例说明
纯数字[^1]、[^2]最常见，渲染时自动按出现顺序编号
单词[^note]、[^source]语义化标签，方便维护长文档
数字+单词[^fn1]、[^ref-source]混合命名，注意连字符要一致
同一标签多次引用[^1] 出现多次同一个脚注可以在正文中多次引用，编号相同
第一次引用。[^1] 第二次引用同一个脚注。[^1]

[^1]: 这个脚注被引用了两次。

顺便提一句，短文档用 [^1] 这种纯数字就够了。但如果你写的是那种有几十个脚注的长文，建议用 [^smith2023] 这种带含义的标签，回头维护的时候一眼就知道哪个脚注是引的哪篇文献。

脚注定义放在哪里

脚注定义可以放在文档中的任意位置，渲染器会自动收集所有脚注并统一显示在页面底部。

推荐做法：

  • 短文档：放在文末，方便管理
  • 长文档：可以放在对应章节的末尾，维护时不用来回翻找
  • 学术论文：统一放在文末，按出现顺序排列
## 第一节

正文内容。[^a]

[^a]: 第一节的脚注。

## 第二节

正文内容。[^b]

[^b]: 第二节的脚注。

平台兼容性对照表

不同 Markdown 解析器和平台对脚注的支持差异很大。我整理了主流平台的兼容性对照：

平台/工具引用式 [^1]行内式 ^[]多段落脚注备注
GitHub✅❌✅2021 年 9 月开始支持
GitLab✅❌✅-
Pandoc✅✅✅支持最全面
Obsidian✅❌✅实测验证
Typora✅❌✅渲染效果优秀
VS Code（内置预览）❌❌❌需安装插件
VS Code + 插件✅❌✅安装 markdown-footnotes 插件
Hugo✅❌✅-
Jekyll✅❌✅需要 kramdown 解析器
语雀❌❌❌不支持 Markdown 脚注
飞书文档❌❌❌不支持 Markdown 脚注
CSDN✅❌⚠️部分支持，行为不稳定
Stack Exchange❌❌❌明确拒绝支持脚注

✅ 支持　❌ 不支持　⚠️ 部分支持

上面这个表里，GitHub、Obsidian、Typora 是我自己实际试过的，Pandoc、Hugo、Jekyll 是看官方文档整理的，语雀、飞书、CSDN 那几个是根据社区反馈汇总的，不一定完全准确。

对了，关于 VS Code 有个事得说——它的内置 Markdown 预览居然不支持脚注。我一开始还以为是自己语法写错了，反复改了好几遍都不显示。后来搜了一下才发现是 VS Code 本身的问题，装了个 "Markdown Footnotes" 插件就好了。如果你也在 VS Code 里写 Markdown，记得先把这个插件装上。

脚注 vs 引用链接：该用哪个

Markdown 中有两种看起来相似但用途不同的语法：

特性脚注 [^1]引用链接 [文字][1]
渲染效果上标编号，页面底部收集行内文字，带链接样式
典型用途学术引用、补充说明超链接跳转
点击行为页面内跳转跳转到外部 URL
自动编号✅ 自动❌ 手动
<!-- 脚注：用于补充说明 -->
这里有个观点需要引用。[^1]

[^1]: 来自某权威论文的论证。

<!-- 引用链接：用于外部链接 -->
更多内容请参考 [Markdown 链接](/markdown/link/) 语法。

<!-- 也可以用 HTML 方式手动模拟脚注 -->
这里需要标注。<sup><a id="note1" href="#fn1">1</a></sup>

<span id="fn1">1. 这是手动模拟的脚注。</span> [<a href="#note1">↑</a>]

简单判断原则：

  • 需要补充说明或学术引用 → 用脚注
  • 需要链接到其他页面 → 用 Markdown 链接
  • 平台不支持脚注且需要上标效果 → 用 HTML <sup> 标签手动模拟

脚注中使用的 Markdown 格式

脚注内部支持大部分 Markdown 格式：

正文内容。[^fmt]

[^fmt]: 脚注内可以使用 **加粗**、*斜体*、`代码` 和 [链接](https://example.com)。
    也可以引用代码块：

        console.log("脚注中的代码")

    列表也支持：

    - 第一项
    - 第二项

注意代码块在脚注中需要缩进 8 个空格（4 个用于脚注续行 + 4 个用于代码块缩进）。

常见问题排查

脚注不显示

按以下顺序排查：

  1. 标签是否一致：正文中 [^note1] 和定义 [^note-1] 必须完全匹配
  2. 冒号后有空格：[^1]: 内容（冒号后要有空格）
  3. 平台是否支持：查看上方兼容性表，确认你使用的平台支持脚注
  4. 多段落缩进：后续段落必须缩进 4 个空格，不是 Tab
  5. 重复定义：同一个标签只能定义一次，重复定义会导致显示异常

脚注编号错乱

脚注编号由渲染器按正文出现的先后顺序自动生成，与你定义标签时用的数字无关：

第二段。[^99]
第一段。[^1]

[^1]: 第一个脚注。
[^99]: 第二个脚注。

渲染后，[^99] 的编号会显示为 1（因为先出现在正文中），[^1] 的编号会显示为 2。

多段落脚注挤成一行

确保后续段落缩进的是 4 个空格而非 Tab。不同解析器对 Tab 的处理不一致，4 个空格兼容性最好。

几个实用建议

用了这么久 Markdown 脚注，我总结了几个习惯：

  • 短文档直接用数字标签 [^1] 就够了，别折腾。但如果你要写一篇有几十个脚注的长文，建议用 [^smith2023] 这种带含义的标签，不然回头改的时候根本分不清谁是谁
  • 脚注定义统一放文末，找起来方便。除非文档特别长，那可以按章节放
  • [^1] 比 ^[] 兼容性好得多，没什么特殊需求就用引用式
  • 脚注内容别写太长，超过三段就该考虑直接放正文里了
  • 发之前一定在目标平台上预览一下，不同平台渲染效果可能差很远

写在最后

说实话 Markdown 脚注的语法本身没几行，几秒钟就能学会。但真正用起来的时候，坑都在细节里——标签写错一个字符、缩进用了 Tab、平台不支持……这些才是让人抓狂的地方。

我的建议是：刚开始用就只记 [^1] 这一种写法，其他花式语法等遇到需求了再学。反正这个语法兼容性最好，在 GitHub、Obsidian、Typora 里都能用。

参考来源：