GFM 擴充語法

GitHub Flavored Markdown 在 CommonMark 基礎上新增的語法與實務注意事項

Overview##

GitHub Flavored Markdown (GFM) 是 GitHub 在 CommonMark 基礎上的超集。它新增了幾項在協作開發中高頻使用的語法，目前已被大多數 Markdown 工具支援。

GFM 額外提供的語法：

功能	CommonMark	GFM
Table	❌	✅
Task List	❌	✅
Strikethrough	❌	✅
Autolink	部分	✅ 擴充
Footnote	❌	✅
Disallowed Raw HTML	不限制	過濾部分標籤

Note

GFM 是 CommonMark 的超集——所有 CommonMark 語法在 GFM 中都有效，反過來則不一定。

Table##

GFM Table 是最常用的擴充功能。用 | 分隔欄位，--- 分隔標題與內容：

| Method | Idempotent | Safe |
| ------ | ---------- | ---- |
| GET    | Yes        | Yes  |
| POST   | No         | No   |
| PUT    | Yes        | No   |
| DELETE | Yes        | No   |

對齊###

用 : 控制欄位對齊方式：

| Left | Center | Right |
| :--- | :----: | ----: |
| text |  text  |  text |

語法	對齊方式
`:---`	靠左（預設）
`:---:`	置中
`---:`	靠右

常見問題###

<!-- ❌ 忘記 header separator -->

| Name | Value |
| Alice | 42 |

<!-- ✅ 必須有 separator row -->

| Name  | Value |
| ----- | ----- |
| Alice | 42    |

<!-- ❌ 欄位內使用未跳脫的 pipe -->

| Expression | Result |
| ---------- | ------ | ---- |
| a          | b      | true |

<!-- ✅ 用 \| 跳脫 -->

| Expression | Result |
| ---------- | ------ |
| a \| b     | true   |

Tip

Table 內不支援多行內容或區塊元素（清單、code block）。如果需要複雜的表格結構，改用 HTML <table> 或考慮拆分內容。

Task List##

在清單項目前加上 [ ] 或 [x] 建立 checkbox：

- [x] Define API schema
- [x] Implement endpoints
- [ ] Write integration tests
- [ ] Update documentation

渲染效果：

Define API schema
Implement endpoints
Write integration tests
Update documentation

巢狀 Task List###

- [ ] Authentication
  - [x] Login endpoint
  - [x] Token refresh
  - [ ] OAuth integration
- [ ] Authorization
  - [ ] Role-based access control

Warning

Task List 是 GFM 專屬語法。在不支援 GFM 的解析器中，[ ] 和 [x] 會被當成純文字顯示。撰寫跨平台文件時需注意。

Strikethrough##

用雙波浪號 ~~ 包裹文字產生刪除線：

<!-- ✅ GFM strikethrough -->

~~deprecated~~ 已被取代

<!-- ❌ 單波浪號不是合法語法 -->

~not strikethrough~

實用場景：

## Changelog

- ~~v1 API endpoints~~ → Replaced by v2
- ~~jQuery dependency~~ → Removed in 3.0

Note

部分解析器（如 Pandoc）支援單波浪號 ~text~，但這不是 GFM 規範。統一使用 ~~ 確保相容性。

Autolink##

CommonMark 要求用 <url> 才能產生連結。GFM 擴充了自動偵測：

<!-- CommonMark：需要角括號 -->

<https://example.com>

<!-- GFM：裸網址自動轉為連結 -->

https://example.com

<!-- GFM：也支援 email -->

user@example.com

自動偵測規則###

GFM Autolink 有嚴格的匹配條件：

條件	說明
Protocol	必須以 `http://` 或 `https://` 開頭
Domain	至少包含一個 `.`
結尾字元	自動排除尾部的 `)`, `.`, `,`, `:` 等標點

<!-- ❌ 沒有 protocol，不會自動連結 -->

example.com

<!-- ❌ 括號內的 URL 可能被截斷 -->

(https://example.com/path_(detail))

<!-- ✅ 複雜 URL 建議用明確語法 -->

[連結文字](<https://example.com/path_(detail)>)

Tip

即使 GFM 支援 autolink，在正式文件中仍建議使用 [文字](url) 語法。明確的連結文字比裸網址更具可讀性和語意。

Footnote##

Footnote 讓你在文末集中補充說明，不打斷主要閱讀流：

Markdown 由 John Gruber 在 2004 年創造[^1]，後來由 CommonMark[^2] 標準化。

[^1]: Gruber 與 Aaron Swartz 共同設計了最初的語法。

[^2]: CommonMark 規範始於 2014 年，由 John MacFarlane 主導。

多段落 Footnote###

這是一個複雜的概念[^detail]。

[^detail]: 第一段解釋。

    第二段補充（需縮排 4 格）。

    ```js
    // 甚至可以包含 code block
    console.log('footnote');
    ```

注意事項###

<!-- ❌ Footnote 標記不能有空格 -->

[^ 1]: This won't work.

<!-- ❌ 未定義的 footnote 會顯示為純文字 -->

See reference[^undefined].

<!-- ✅ 標記與定義必須配對 -->

See reference[^ref].

[^ref]: Definition here.

Warning

Footnote 的渲染位置由解析器決定，通常出現在頁面最底部。不同平台的呈現方式可能不同——GitHub 會在原文位置顯示 tooltip，而部分 SSG 框架會將 footnote 收集到頁尾。

Disallowed Raw HTML##

GFM 出於安全考量，會過濾部分 HTML 標籤。這些標籤的內容會被保留，但標籤本身會被移除：

被過濾的標籤
`<title>`
`<textarea>`
`<style>`
`<xmp>`
`<iframe>`
`<noembed>`
`<noframes>`
`<script>`
`<plaintext>`

<!-- 這段在 GFM 中不會執行 -->
<script>alert('xss')</script>

<!-- 安全的 HTML 標籤仍可使用 -->
<details>
<summary>展開更多</summary>

這裡的內容預設是摺疊的。

</details>

Tip

<details> + <summary> 是 GFM 中常用的摺疊內容模式，特別適合 FAQ、長 log、或可選的詳細說明。

Summary##

GFM 是 CommonMark 的超集，新增 Table、Task List、Strikethrough、Autolink、Footnote
Table 必須有 separator row，欄位內的 | 需要 \| 跳脫
Task List 用 [ ] / [x]，僅在支援 GFM 的環境中有效
Strikethrough 統一使用 ~~，不用單波浪號
Autolink 雖方便，正式文件仍建議用明確連結語法
Footnote 標記與定義必須配對，渲染位置因平台而異
GFM 會過濾 <script>、<iframe> 等潛在危險標籤

留言 (0)

登入後即可留言