Markdown 擴充語法完全指南：GFM、Pandoc、MultiMarkdown 比較與實戰

Markdown 擴充語法是什麼？為什麼需要它？

如果你用過一段時間的 Markdown，大概遇過這種困惑：明明在 GitHub 上能正常渲染的表格，換到某個部落格平台就變成了一堆豎線和短橫線。這是因為你用到了 Markdown 擴充語法（markdown extensions）。

John Gruber 在 2004 年設計 Markdown 時，定義了一套相當精簡的基礎語法——標題、列表、連結、圖片、程式碼、粗體、斜體，差不多就這些。他當時的目標是讓純文字「易讀易寫」，而不是做一個全功能的排版系統。

但現實中寫文件的需求遠不止於此。你需要表格來展示資料，需要腳註來標注引用來源，需要任務列表來追蹤進度，需要數學公式來寫學術筆記。這些功能統統不在原始 Markdown 規範裡。

於是各路人馬開始各自擴充。GitHub 加了表格和任務列表，Pandoc 加了腳註和數學公式，MultiMarkdown 加了引用和元資料……這就形成了今天我們看到的「Markdown 擴充語法」生態——百花齊放但也多少有點混亂。

說實話，理解了這個背景，很多平台之間渲染結果不一致的問題就能解釋通了。不是你寫錯了，而是它們支援的擴充集合不一樣。

四大主流 Markdown 擴充變體

目前影響最大的 Markdown 變體（也叫「方言」或 "flavor"）有四個，它們構成了擴充語法的主要版圖。

CommonMark：只管標準，不擴充

CommonMark 專案始於 2014 年，目的是解決原始 Markdown 規範中的歧義問題。它做了一件很重要的事：把基礎 Markdown 的行為用精確的規範和測試套件定義清楚。根據 CommonMark 官方規範，CommonMark 本身不包含任何擴充——沒有表格，沒有腳註，沒有刪除線。

但 CommonMark 的各種解析器實作（比如 JavaScript 的 markdown-it、PHP 的 league/commonmark）通常提供了可選的擴充機制，可以在 CommonMark 基礎上開啟 GFM 表格、刪除線等功能。換句話說，CommonMark 提供了標準化的地基，擴充是你在上面自己加的樓層。

GFM（GitHub Flavored Markdown）：用得最廣泛的擴充集

GFM 是 GitHub 基於 CommonMark 定義的擴充規範。根據 GitHub 官方文件，GFM 是 CommonMark 的嚴格超集——每個合法的 CommonMark 文件在 GFM 中都合法。

GFM 在 CommonMark 基礎上加了四個官方擴充：

擴充語法範例用途
表格| 欄1 | 欄2 |結構化資料展示
刪除線~~刪除的文字~~標記廢棄內容
自動連結直接寫 URL 自動變連結免去手動加 <> 的麻煩
任務列表- [ ] 待辦 / - [x] 已完成專案管理和待辦追蹤

我個人的感覺是，GFM 這四個擴充選得非常精準——覆蓋了開發者在 GitHub 上寫 README 和文件時最常用的功能。如果你寫的內容主要發在 GitHub 或 GitLab 上，GFM 擴充基本就夠用了。

Pandoc Markdown：擴充最豐富的專業級方案

Pandoc 是學術寫作和文件轉換領域的瑞士刀。它定義了自己的 Markdown 方言，提供了極其豐富的擴充庫。根據 Pandoc 官方手冊，你可以透過 +擴充名 或 -擴充名 的方式精細控制每個擴充的開關。

一些典型的 Pandoc 擴充用法：

pandoc -f commonmark+table_captions+footnotes -t html input.md

# 啟用 YAML 元資料區塊和圍欄程式碼區塊
pandoc -f markdown+yaml_metadata_block+fenced_code_blocks -t pdf input.md

Pandoc 支援的擴充涵蓋了幾十種功能——腳註、定義列表、上標下標、數學公式、引用文獻（citations）、YAML 元資料區塊、圍欄 div（fenced divs）、行內屬性（inline attributes）等等。它甚至提供了相容 MultiMarkdown 語法的擴充選項。

對了，有一點值得注意：Pandoc 可以在多種 Markdown 模式下工作（markdown、commonmark、gfm、commonmark_x），每種模式可用的擴充集合略有不同。具體可以查閱 Pandoc 手冊的 "Non-default extensions" 章節。

MultiMarkdown：學術寫作的先驅

MultiMarkdown 由 Fletcher Penney 建立，是最早對原始 Markdown 進行大幅擴充的方案之一，主要面向學術和技術文件寫作。它添加了腳註、表格、引用（citations）、元資料、交叉引用等出版級別的功能。

MultiMarkdown 有自己的解析器，不是基於 CommonMark 的。它的語法規則跟 GFM 和 Pandoc 有重疊但也有差異。目前 MultiMarkdown 的使用範圍相對較小，很多 MultiMarkdown 的功能都可以透過 Pandoc 的相容擴充來實作。除非你有遺留的 MultiMarkdown 文件，否則一般建議用 Pandoc 作為替代。

PHP Markdown Extra：重要的歷史傳承

除了上面四大變體，還有一個繞不開的名字是 PHP Markdown Extra。它是 Michel Fortin 在 PHP Markdown 函式庫基礎上添加的擴充集，引入了表格、定義列表、腳註、縮寫（abbreviations）、程式碼區塊圍欄等功能。

雖然 PHP Markdown Extra 本身的影響力在下降，但它的很多語法設計被其他解析器借鑑了。比如 markdown-it 的 markdown-it-deflist 外掛就沿用了類似的定義列表語法。在討論 markdown extra 的時候，基本上是在討論這一脈的擴充傳統。

各擴充功能在各變體中的支援情況

這個表格是根據 Markdown Guide、Pandoc 手冊 和 GitHub 文件 交叉整理的：

擴充功能語法概要GFMPandocMultiMarkdownCommonMark 解析器
表格| 欄1 | 欄2 |✅ 原生✅✅多數支援（作為外掛）
刪除線~~文字~~✅ 原生✅❌多數支援
任務列表- [ ] / - [x]✅ 原生✅❌部分支援
腳註[^1]❌✅✅需外掛
定義列表術語 : 定義❌✅✅需外掛
上標/下標H~2~O / X^2^❌✅✅需外掛
數學公式$E=mc^2$❌✅✅需外掛
自動連結裸 URL 自動連結✅ 原生✅✅多數支援
YAML 元資料--- 包裹的 front matter❌✅✅需外掛
引用文獻[@key]❌✅✅需外掛
圍欄程式碼區塊```lang✅✅✅多數支援
語法高亮圍欄程式碼區塊指定語言✅✅✅需設定
標題 ID{#custom-id}❌✅✅需外掛
高亮標記==高亮==❌✅❌需外掛

從這個表可以看出一個很清楚的趨勢：GFM 覆蓋面窄但用得最廣，Pandoc 覆蓋面最廣但需要設定。 你對擴充功能的需求越複雜，就越可能需要 Pandoc。

實測：擴充語法在不同平台上的相容性

光看規範文件有時候不夠直觀，我實際測試了幾個常見的擴充語法在主流平台上的渲染效果。

GitHub / GitLab

GitHub 和 GitLab 都支援 GFM，所以表格、刪除線、任務列表、自動連結這些都沒問題。但 GitHub 的 Markdown 渲染不支援腳註——你在 GitHub README 裡寫 [^1]，它不會被渲染為腳註連結，只會原樣顯示。這一點讓不少從學術寫作轉到 GitHub 的朋友踩了坑。

GitLab 的擴充支援比 GitHub 稍寬，支援腳註和數學公式（透過 KaTeX）。

VS Code（內建預覽 + Markdown Preview Enhanced 外掛）

VS Code 內建的 Markdown 預覽支援 GFM 擴充。如果安裝了 "Markdown Preview Enhanced" 外掛，還額外支援腳註、數學公式（KaTeX/MathJax）、Mermaid 圖表、目錄（TOC）等更多擴充。

我的建議是，如果你在 VS Code 裡寫 Markdown，裝一個 Markdown Preview Enhanced 會省很多事。

Typora

Typora 對擴充語法的支援相當全面——表格、腳註、數學公式、上標下標、高亮、目錄都支援。它底層用的是不同的解析器，基本上把 GFM 擴充和 Pandoc 的常用擴充都包進去了。如果你想要一個「開箱即用支援最多擴充」的桌面編輯器，Typora 是個不錯的選擇。

靜態網站產生器（Hugo / Jekyll）

Hugo 預設支援 GFM 擴充，也支援 Goldmark 解析器的各種擴充選項。Jekyll 使用 kramdown 作為預設解析器，支援表格、腳註、定義列表等。兩者都可以透過設定檔開啟或關閉特定的擴充。

有一次我用 Hugo 寫部落格，預設設定下圍欄程式碼區塊裡的數學公式怎麼也渲染不出來，排查了半天才發現是 Goldmark 的擴充沒有在 hugo.toml 裡明確開啟。這種「預設不開」的設計在靜態網站工具裡很常見，遇到功能不生效的時候，先檢查設定。

怎麼選擇適合自己的 Markdown 變體？

選擇哪個 Markdown 變體，主要取決於你的使用場景：

場景一：寫 GitHub README 或專案文件→ 直接用 GFM 就好。GitHub 只支援 GFM 擴充，你用了 Pandoc 的腳註語法也不會被渲染。專注於表格、任務列表、程式碼區塊這三個核心功能。

場景二：寫部落格或個人筆記→ 推薦 Typora 或 VS Code + Markdown Preview Enhanced。它們的擴充支援全面，大部分擴充語法開箱即用。如果你的部落格用 Hugo 或 Jekyll，記得對照建置工具的文件確認支援哪些擴充。

場景三：寫學術論文或技術書籍→ Pandoc 是首選。它的腳註、引用文獻、數學公式、YAML 元資料、交叉引用這些功能是其他變體難以匹敵的。配合 LaTeX 範本可以輸出高品質的 PDF。

場景四：需要最大相容性（多平台發佈）→ 堅守 CommonMark 基礎語法 + GFM 擴充。這套組合幾乎在所有平台上都能正確渲染。避免使用腳註、定義列表、上標下標等「進階」擴充，或者準備好多個版本的文件。

常見問題

CommonMark 和 GFM 是什麼關係？

GFM 是 CommonMark 的嚴格超集。你可以理解為 CommonMark 是地基，GFM 在上面蓋了四間房（表格、刪除線、自動連結、任務列表）。所有合法的 CommonMark 文件在 GFM 中也合法，反過來則不一定。

Markdown 擴充語法會繼續分裂嗎？

這個問題在 CommonMark 社群 已經討論了很多年。目前看來，擴充語法不太可能統一到一個標準下——不同使用場景的需求差異太大了。更現實的做法是：CommonMark 繼續作為穩定的核心標準，各變體在它之上按需擴充。GitHub 將 GFM 也做了正式規範定義，這是一個積極訊號。

Pandoc 的擴充這麼多，該怎麼入門？

不需要一次學完所有擴充。我的經驗是從這三個開始：

  1. yaml_metadata_block — 用 YAML 管理文件元資料
  2. footnotes — 寫長文件必備
  3. fenced_code_blocks — 比縮排式程式碼區塊好用得多

其他擴充等你遇到了具體需求再去查 Pandoc 手冊就行。

在 GitHub 上能用腳註嗎？

不能。截至 2026 年，GitHub 的 Markdown 渲染器不支援腳註語法。如果你需要在 GitHub 文件裡加註，可以用 HTML 超連結跳轉到頁面底部的手動「註」章節，或者用 <sup> 標籤做上標標記。

markdown-it、marked、showdown 這些解析器有什麼區別？

它們都是 JavaScript 的 Markdown 解析器，區別在於對擴充的支援方式：

  • markdown-it — 嚴格遵循 CommonMark 規範，透過外掛添加擴充，設計最模組化
  • marked — 速度最快，預設支援 GFM 擴充，但擴充機制不如 markdown-it 靈活
  • showdown — 也支援 GFM，更適合瀏覽器端使用

如果你在做一個 Web 應用需要整合 Markdown 解析，markdown-it 的外掛生態是三者中最豐富的。

參考來源：