CommonMark 與 GFM Markdown Spec 的差異:Table 與 Strikethrough 實測

TL;DR — CommonMark 與 GFM Markdown 的差異

• 在 GitHub 上常被稱為「GitHub Markdown 語法」的元素中,表格、刪除線、任務清單、URL 自動連結其實不是標準,而是擴展。CommonMark 是 Markdown 的「標準規格」,只嚴格定義標題、清單、強調、連結、圖片、程式碼、引用等基礎語法。
• GFM(GitHub Flavored Markdown)是 GFM spec 自稱「CommonMark 的嚴格超集」的方言。它在 CommonMark 之上新增了表格、刪除線、任務清單、擴展自動連結、raw HTML 限制這 5 個擴展。
• GitHub.com 上能用的 [!NOTE] 提示框(callout)、表情符號短碼、@mention、issue 參照、Mermaid 圖表、數學公式、腳注,都不是 GFM spec 的內容,而是 GitHub.com 專屬的層級。在 GitHub 之外基本上不會運作。
• 段落內只換行一次(soft break)時是否變成 <br>,CommonMark 與 GFM spec 的規定相同(不會變成 <br>)。只有 GitHub.com 的 issue/PR 留言欄是例外,會把一次換行當作換行處理,與 .md 檔案的行為不同。
• 如果不知道該用哪種方言:純 CommonMark 範圍內撰寫相容性最高,GitHub 為中心的話用到 GFM 擴展就夠了。
• FormatArc 的 Markdown to HTML 轉換工具 支援 GFM 擴展(表格、刪除線、任務清單、自動連結),也可以用來確認自己的 Markdown 是否依賴 GFM 擴展。

重點: 表格不包含在 CommonMark 核心規格中。在 GFM spec 中,表格與刪除線、任務清單、擴展自動連結、raw HTML 限制並列定義為擴展功能。

CommonMark 與 GFM 的關係 — GFM 是以 CommonMark 為基礎的擴展規格

CommonMark在新分頁中開啟 是把原本模糊的 Markdown 語法搭配測試套件嚴格重新定義的專案。目標是消除各程式庫之間的差異,讓任何符合規格的解析器都產生相同的結果。作為規格,它刻意不採用擴展,只規定標題、段落、清單、連結、圖片、強調、程式碼、引用這些核心語法。

GFM(GitHub Flavored Markdown)在新分頁中開啟 是 GitHub 使用的 Markdown 方言,GFM spec 自己描述它是「CommonMark 的嚴格超集(strict superset)」。從語法關係來說:

• 正確的 CommonMark 文件在 GFM 解析器中會以完全相同的方式渲染
• GFM 只是在 CommonMark 上「新增」了一些擴展,並未更動核心語法

不過「超集」這個說法只在 GFM spec 的說明範圍內成立。如果納入 GitHub.com 的實際渲染、各程式庫的實作、以及 CommonMark 最新版本的細微差異,就會有例外存在。本文會把「GFM spec 定義的擴展」與「GitHub.com 自行附加的功能」分開整理。

比較表 — CommonMark 與 GFM 的功能對照

重點在於三欄的分法。表格、刪除線等是 GFM spec 的擴展,所以任何支援 GFM 的解析器都能在 GitHub 之外使用。而提示框、表情符號、腳注不在 GFM spec 中,只有在 GitHub.com(或仿照它的平台)才有保障。

哪些 GFM 擴展是預設啟用的 — 6 個渲染器實測

上面的比較表說明的是「各規格定義了什麼」,但你手邊的解析器在預設設定下實際做了什麼並不清楚。所以做了實測。將相同的 Markdown 片段(管線表格、~~x~~、~x~、- [ ] todo、裸 URL、腳注 [^1])分別通過 5 種 JavaScript 解析器與 GitHub 官方 Markdown API(2026-07-31 實測。重現腳本與結果已提交至儲存庫的 scripts/benchmarks/commonmark-vs-gfm/)。

從實測中可以看到:

• 同樣的 ~~x~~,marked / remark-gfm / GitHub 輸出 <del>,markdown-it 輸出 <s>。即便都是「GFM 對應」的解析器,元素名稱本身就不同
• GFM spec 的刪除線規則允許 1 個或 2 個波浪線。marked / remark-gfm / GitHub 會把 ~x~ 也當作刪除線,但 markdown-it 要求必須是 2 個波浪線,所以 ~x~ 保持為文字
• GitHub 官方 Markdown API 在預設的 markdown 模式下會把 - [ ] 保留為方括號文字。輸出 <input type="checkbox"> 的只有用於留言情境的 gfm 模式,README 中看到的核取方塊並非所有 endpoint 都會產出
• markdown-it 的 default 預設值啟用表格與刪除線,但裸 URL 自動連結(linkify)是關閉的。「預設就支援 GFM」對它來說只對了一半
• 不支援腳注的解析器不會忽略 [^1]: note,而是把它解釋為連結參照定義。結果 text[^1] 會悄悄變成 <a href="note">^1</a>。相反地,remark-gfm 與 GitHub 即使腳注不在 GFM spec 中,也會將其渲染為腳注

想確認自己的 Markdown 在 GFM 對應解析器下會怎麼轉換,直接貼到 Markdown to HTML 轉換工具就能立即看到結果。marked(gfm: true)完全在瀏覽器內執行。

CommonMark 為什麼沒有表格 — 核心規格刻意排除

CommonMark 規格刻意將表格排除在核心語法之外。用管線與連字號組成的表格(| col | col |)是在 GFM spec 中定義的,章節標題本身就是「Tables (extension)在新分頁中開啟」— GFM 自己就把表格標記為擴展功能而非核心語法。同樣的「(extension)」標記也出現在刪除線、任務清單、擴展自動連結、raw HTML 限制上,它們都是「擴展」而非「核心」。

換言之,未啟用擴展的純 CommonMark 渲染器會把 | col | 當作帶有管線符號的段落,而 GFM 對應的渲染器才會輸出 <table>。這個脈絡在 CommonMark 論壇的討論串在新分頁中開啟與 commonmark-spec#393在新分頁中開啟中反覆被討論,表格不在核心規格範圍內這件事可以從原始規格中確認。

想確認某個特定渲染器是否把表格當作 GFM 擴展來處理,把兩行表格貼到轉換工具看是否輸出 <table> 就知道了。

純文字是有效的 CommonMark 文件嗎

用程式驗證 Markdown 時常會遇到一個疑問:「純粹的純文字段落也算有效的 Markdown 嗎」。CommonMark spec 在 2.1 節「Characters and lines」中直接回答了這個問題。

Any sequence of characters is a valid CommonMark document.

也就是說,不存在「無效的 CommonMark 文件」。解析不會失敗,它只判斷文字中包含哪些語法元素。一般的行排列由 4.8 節「Paragraphs」涵蓋。

A sequence of non-blank lines that cannot be interpreted as other kinds of blocks forms a paragraph.

因此,只含普通句子的檔案就是「段落集合」,是有效的 CommonMark 文件(0.31.2 spec 的 2.1 節在新分頁中開啟與 4.8 節在新分頁中開啟)。而且 GFM spec 是 CommonMark 的嚴格超集,所以同樣的文字也是有效的 GFM 文件。擴展只會新增語法,不會讓既有文字變成無效。市面上「Markdown 驗證工具」檢查的是風格約定或渲染預期,而非語法錯誤,原因就在規格層級上 Markdown 不存在語法錯誤。

純文字不再被視為段落的邊界只有一個,由同一個 4.8 節規定:

However, the first line may be preceded by up to three spaces of indentation. Four spaces of indentation is too many:

行首縮排在半形空格 3 個以內仍然是段落。4 個就會變成 4.4 節在新分頁中開啟的 indented code block。同節還規定 "An indented code block cannot interrupt a paragraph, so there must be a blank line between a paragraph and a following indented code block." — 段落後緊接內容前若沒有空行,就不會變成程式碼區塊。

   半形空格 3 個的縮排。
這裡都是一個段落。

     空行之後的 4 個縮排。
     這是程式碼區塊。

規則就是這樣。空行後縮排 4 個之前,普通的文字就是普通的文字。

實務上這代表:如果你在 CI 管線裡用 Markdown linting 工具做格式檢查,不要期望它會報「語法錯誤」,因為根本不存在這種錯誤。它只能檢查的是風格規則(例如標題層級跳級、段落長度、連結格式等)。

實際轉成 HTML 時有什麼不同

只處理 CommonMark 的解析器與 GFM 對應的解析器,即使輸入相同的 Markdown,輸出的 HTML 也會不同。用下面的輸入比較看看:

| 商品 | 庫存 |
| --- | --- |
| 蘋果 | 3 |

~~售罄~~ 有庫存

- [x] 確認入庫
- [ ] 更換價目表

CommonMark 專用的解析器會把 | 商品 | 庫存 | 這行當作帶有管線符號的段落輸出,~~售罄~~ 也不會變成刪除線而是保留波浪線文字,- [x] 則變成普通的清單項目。GFM 對應的解析器則會輸出包含 <table>、<del>、<input type="checkbox"> 的 HTML。

所以當你覺得「Markdown 看起來壞掉了」,原因很可能就是平台之間的方言差異。想確認自己的 Markdown 是否依賴 GFM 擴展,把內容貼到 Markdown to HTML 轉換工具看輸出的 HTML 是最快的方式。

GFM 為 CommonMark 新增的 5 個擴展

表格(Table)

用管線 | 與連字號 - 組成的表格。CommonMark 沒有表格定義,所以表格是 GFM 的擴展功能。定義在 GFM spec 的 Tables (extension)在新分頁中開啟 節(GFM spec 章節 4.10)。只實作 CommonMark 的渲染器不會把表格畫出來,管線符號會原封不動地保留。對齊指定(:--- / :---: / ---:)或儲存格內管線的逸出等細節,可參考上面的比較表與實測表。

刪除線(Strikethrough)

~~要刪掉的文字~~ 會變成 <del> 元素。用 2 個波浪線包裹的寫法是 GFM 擴展,不包含在 CommonMark 中。請參考 GFM spec 的 Strikethrough (extension)在新分頁中開啟 節(GFM spec 章節 6.5)。是否也允許 1 個波浪線(~x~)則因解析器而異,上面的實測中只有 markdown-it 要求必須是 2 個。

任務清單(Task List)

在清單項目開頭寫 - [ ](未完成)或 - [x](已完成)就會渲染為核取方塊。這個語法定義在 GFM spec 的 Task list items (extension)在新分頁中開啟 節(GFM spec 章節 5.3)。在 GitHub 上,issue 或 PR 本文中的核取方塊可以點擊切換狀態,但那個「點擊切換」的行為是 GitHub.com 的功能,普通的 HTML 渲染器只會輸出靜態的核取方塊。

擴展自動連結(Extended Autolinks)

直接寫 https://example.com 就會自動變成連結。CommonMark 中要把 URL 變成連結得用尖括號包起來(<https://example.com>),但 GFM 也會偵測沒有括號的裸 URL 並將其連結化。這個裸 URL 行為規定在 GFM spec 的 Autolinks (extension)在新分頁中開啟 節(GFM spec 章節 6.9),與 CommonMark 自身的尖括號自動連結是不同的機制。

Raw HTML 限制(Disallowed Raw HTML)

CommonMark 與 GFM 都允許在 Markdown 中嵌入 raw HTML。差異在於 GFM 會把 <script> / <iframe> / <style> 等極少數標籤標記為「禁止的 raw HTML」並使其無效。此外,GitHub.com 在另一個層級施加更嚴格的 HTML sanitize(移除屬性等)。FormatArc 的轉換工具只做語法轉換,如果你轉換了不可信的輸入,輸出 HTML 請另外做 sanitize。

各規則在哪裡定義 — 直接查規格原文

想以一次資訊確認上述內容時,請直接查規格本身,而不是第三方的整理:

• 核心語法由 CommonMark Spec在新分頁中開啟(John MacFarlane 著)定義。涵蓋標題、段落、清單、連結、圖片、強調、程式碼、引用,但明確地不定義表格、刪除線、任務清單、裸 URL 自動連結。
• 本文提到的 4 個 GFM 擴展各自在 GitHub Flavored Markdown Spec在新分頁中開啟 中擁有獨立章節,每個標題都帶有「(extension)」:
  • Tables (extension)在新分頁中開啟 — GFM spec 章節 4.10
  • Task list items (extension)在新分頁中開啟 — GFM spec 章節 5.3
  • Strikethrough (extension)在新分頁中開啟 — GFM spec 章節 6.5
  • Autolinks (extension)在新分頁中開啟 — GFM spec 章節 6.9

各 GFM 標題中的「(extension)」標記,是規格本身在表明這些是 CommonMark 的附加而非核心語法。禁止的 raw HTML 規則同樣定義在 GFM spec 的 Disallowed Raw HTML (extension)在新分頁中開啟 節中。

非 GFM Spec 而是 GitHub.com 專屬的功能

以下功能常被介紹為「GitHub 的 Markdown」,但 GFM spec 中並沒有。請視為只在 GitHub.com(以及仿照它的少數服務)上運作的功能。

• 提示框(callout)— > [!NOTE] / > [!TIP] / > [!IMPORTANT] / > [!WARNING] / > [!CAUTION] 共 5 種。以帶色塊的提示框形式渲染。
• 表情符號短碼 — :smile: 這樣的 :name: 寫法。標準 Markdown 沒有表情符號的概念。
• @mention / issue・PR 參照 / commit SHA — 自動將 @username、#123、commit hash 連結化。沒有儲存庫上下文就失去意義的功能。
• Mermaid 圖表、數學公式 — ```mermaid 程式碼區塊與 $...$ 公式。同樣是 GitHub.com 渲染管線的附加功能。
• 腳注 — [^1] 格式。GitHub.com 支援,但 GFM spec 中沒有。remark-gfm 或 Hugo 的 Goldmark 等工具可能把腳注與 GFM 系擴展一起啟用,但那是各實作的判斷。

使用了這些功能的 Markdown 如果搬到 GitHub 之外(把 README 原封不動貼到部落格、文書工具等),大部分會原樣以純文字顯示。把它們當作 GitHub.com 專屬的寫法比較安全。

一個常見的實際情境是:團隊內部文件用 [!NOTE] 和 @mention 寫得很順手,結果要發表成公開文件時,這些語法全數失效。與其事後重寫,不如一開始就區分「內部 GitHub 上下文」和「對外發布內容」的語法範圍。

段落內換行(hard line break)處理的差異

這是誤解比較多的地方。無論 CommonMark 還是 GFM spec,段落中只換行一次(soft break)都不會變成 <br>,前後行會合併為一個段落。要強制產生 <br>,需要行尾放 2 個半形空格、行尾放反斜線 \、或直接寫 <br> 標籤。CommonMark 與 GFM 在這點上行為一致。另外,反斜線也可以用來逸出符號,使其不被解讀為格式。

行尾 2 個空格有不會生效的位置,同一個 4.8 節規定 "Final spaces or tabs are stripped before inline parsing, so a paragraph that ends with two or more spaces will not end with a hard line break:"。行尾空格生效的位置是段落內行與行之間,段落結尾處則無效。

例外是 GitHub.com 的 issue / PR / Discussion 留言欄,那裡設為「一次換行直接變成 <br>」。但同樣在 GitHub 上,.md 檔案(README 或文檔)仍然遵循 CommonMark / GFM 標準行為,需要 2 個空格或 \。「在 GitHub 留言欄換行成功了但 README 中不行」就是這個原因。

哪些平台與工具用哪種方言

更精確地說,是「純 CommonMark」、「CommonMark + GFM 擴展」、「自定義方言」哪一種比較接近。整理具有代表性的:

即使寫著「支援 GFM」,也不一定包含 GitHub.com 專屬的提示框或表情符號。反過來,「只支援 CommonMark」的工具加上外掛後通常也能使用 GFM 擴展。最終還是查你使用的程式庫或服務的文件中「哪些擴展是啟用的」比較確定。

如何確認你的環境是否支援 GFM

不需要深入調查,按以下步驟大致就能判斷:

• 分別寫一個表格(| col |)、刪除線(~~text~~)、任務清單(- [ ]),能渲染出來就代表支援 GFM 擴展
• 如果用程式庫,查設定。marked 需要 gfm: true,remark 需要 remark-gfm 外掛,markdown-it 預設啟用 GFM 表格與刪除線(但裸 URL 自動連結不啟用 linkify 就關閉。參照上面的實測表)
• 如果是靜態網站產生器,查設定檔案。Hugo 看 markup.goldmark.extensions,Astro 看 markdown.remarkPlugins 中是否有 remark-gfm

如果只是想確認某個 Markdown 檔案是否依賴 GFM 擴展,貼到 Markdown to HTML 轉換工具看表格與刪除線有沒有變成 HTML 就知道了。

應該以哪種方言撰寫 Markdown

• 相容性最高的是限制在純 CommonMark 範圍內。幾乎所有渲染器都能正確顯示。
• 以 GitHub 或同級平台(GitLab、大多數文書工具)為前提,用到 GFM 擴展(表格、刪除線、任務清單、自動連結)沒有問題。實務上這個範圍就是標準。
• 提示框([!NOTE] 等)、表情符號短碼、@mention、Mermaid、腳注,請以「在 GitHub.com 之外會壞」為前提使用。README 中很方便,但複製到部落格就變純文字了。
• 如果要考慮分發或移植,盡量避免混合 raw HTML。無論 CommonMark 還是 GFM,包含 raw HTML 的文件會受到 sanitize 與渲染器實作的影響。

FormatArc 的 Markdown 轉換工具用哪種方言

FormatArc 的 Markdown to HTML 轉換工具內部以 marked 搭配 gfm: true 執行。因此:

• GFM spec 的擴展(表格、刪除線、任務清單、擴展自動連結)會直接轉為 HTML
• 段落內換行(soft break)的行為等同 breaks: false,不會變成 <br>。與 CommonMark / GFM spec 一致,與 GitHub.com 留言欄的換行行為不同
• GitHub.com 專屬的提示框([!NOTE] 等)、表情符號短碼、@mention、Mermaid、腳注不支援,因為它們不是 GFM spec 的功能

反向的 HTML to Markdown 轉換,輸出的 Markdown 也是包含表格與刪除線在內的 GFM 側格式。兩者都完全在瀏覽器內處理,不需要註冊也不需要上傳。貼上公司內部的未公開文件也不會傳送到外部。

常見問題

CommonMark 與 GFM Markdown,應該用哪種寫?

相容性最高的是純 CommonMark 範圍。以 GitHub 或同級平台為前提的話,用到 GFM 擴展(表格、刪除線、任務清單、自動連結)也沒問題。[!NOTE] 等 GitHub.com 專屬功能請以「在 GitHub 之外會壞」為前提使用。

CommonMark 有表格語法嗎?

沒有。表格是 GFM 擴展功能,不包含在 CommonMark 規格中。只實作 CommonMark 的渲染器會把 | col | 原樣顯示為帶有管線符號的文字。表格沒渲染出來時,先確認表頭列與分隔列的欄數是否一致。

GitHub 的 [!NOTE] 提示框在其他工具中能用嗎?

基本上只在 GitHub.com(以及少數仿照它的服務)運作。GFM spec 沒有提示框的定義,所以其他 Markdown 渲染器會把 > [!NOTE] 當作引用區塊內的文字原樣顯示。

Obsidian 或 Notion 是 GFM 相容的嗎?

不是完全相容。Obsidian 以 CommonMark 為基礎,支援 GFM 表格與任務清單,同時也有 [[wikilink]] 等自定義記法。Notion 也是自定義方言,匯出時的 Markdown 偏 GFM,但編輯器內的記法是 Notion 專屬。使用前請查各工具的文件確認支援的記法。

FormatArc 用哪種方言轉換?

偏 GFM。以 marked 搭配 gfm: true 執行,因此支援表格、刪除線、任務清單、自動連結。段落內換行不會變成 <br>(與 CommonMark / GFM spec 一致),所以貼上後如果發現段落被合併,不是轉換器的 bug,而是 GFM 標準行為。GitHub.com 專屬的提示框、表情符號、mention、Mermaid、腳注不支援。

總結

CommonMark 是 Markdown 的標準規格,GFM 是在其上加上 5 個擴展(表格、刪除線、任務清單、擴展自動連結、raw HTML 限制)的方言。GitHub.com 上看到的提示框、表情符號、@mention、Mermaid、腳注,是再上一層的 GitHub.com 專屬層級,在 GitHub 之外基本上不會運作。

不知道該用哪種方言時:重視相容性就選 CommonMark,GitHub 為中心就用 GFM 擴展,GitHub.com 專屬功能以「會壞」為前提,記住這三點就不會太困惑。

實際寫 Markdown 時最容易踩到的是「在 GitHub 上沒問題,換到別的平台就壞了」。與其事後排查,不如在動筆前先確認目標平台的方言範圍。

想確認自己的 Markdown 是否依賴 GFM 擴展,或者想把 Markdown 轉成 HTML,可以用 Markdown to HTML 轉換工具。完全在瀏覽器內完成,不需要註冊也不需要上傳。貼上後如果發現段落被合併,不是轉換器的 bug,而是 GFM 標準行為。