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 連結](/zh/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 個用於程式碼區塊縮排）。
常見問題排查
腳註不顯示
按以下順序排查：
- 標籤是否一致：正文中
[^note1]和定義[^note-1]必須完全匹配 - 冒號後有空格：
[^1]: 內容（冒號後要有空格） - 平台是否支援：查看上方相容性表，確認你使用的平台支援腳註
- 多段落縮排：後續段落必須縮排 4 個空格，不是 Tab
- 重複定義：同一個標籤只能定義一次，重複定義會導致顯示異常
腳註編號錯亂
腳註編號由渲染器按正文出現的先後順序自動產生，與你定義標籤時用的數字無關：
第二段。[^99]
第一段。[^1]
[^1]: 第一個腳註。
[^99]: 第二個腳註。渲染後，[^99] 的編號會顯示為 1（因為先出現在正文中），[^1] 的編號會顯示為 2。
多段落腳註擠成一行
確保後續段落縮排的是 4 個空格而非 Tab。不同解析器對 Tab 的處理不一致，4 個空格相容性最好。
幾個實用建議
用了這麼久 Markdown 腳註，我總結了幾個習慣：
- 短文件直接用數字標籤
[^1]就夠了，別折騰。但如果你要寫一篇有幾十個腳註的長文，建議用[^smith2023]這種帶含義的標籤，不然回頭改的時候根本分不清誰是誰 - 腳註定義統一放文末，找起來方便。除非文件特別長，那可以按章節放
[^1]比^[]相容性好得多，沒什麼特殊需求就用引用式- 腳註內容別寫太長，超過三段就該考慮直接放正文裡了
- 發之前一定在目標平台上預覽一下，不同平台渲染效果可能差很遠
寫在最後
說實話 Markdown 腳註的語法本身沒幾行，幾秒鐘就能學會。但真正用起來的時候，坑都在細節裡——標籤寫錯一個字元、縮排用了 Tab、平台不支援……這些才是讓人抓狂的地方。
我的建議是：剛開始用就只記 [^1] 這一種寫法，其他花式語法等遇到需求了再學。反正這個語法相容性最好，在 GitHub、Obsidian、Typora 裡都能用。
參考來源：
- Markdown Guide - Extended Syntax (Footnotes)（Markdown 社群權威參考）
- GitHub Blog - Footnotes Now Supported（GitHub 官方公告）
- Stack Overflow - How to Add Footnotes to GitHub Flavored Markdown（15.3 萬瀏覽量）
- Pandoc Manual - Footnotes（Pandoc 官方文件）