GitHub 風格 Markdown：完整指南

表格：用純文字呈現結構化資料

表格是原始 Markdown 最令人想念的功能。直線符號（|）分隔欄位，一列由連字號組成的分隔線區分表頭與內容，分隔線裡的冒號則決定對齊方式。

| 功能     | 原始 Markdown | GFM |
|:---------|:------------:|----:|
| 表格     |      無      | 有  |
| 待辦清單 |      無      | 有  |
| 刪除線   |      無      | 有  |

分隔線如何決定對齊

對齊全靠那一列。把冒號想成磁鐵，文字會被吸過去：

• :--- 或單純的 --- 是靠左對齊，也是預設值。
• :---: 置中，適合「有／無」這類短短的狀態字。
• ---: 靠右，數字與金額用這個最好讀。

直線符號在原始碼裡不必對得整整齊齊，解析器只在乎符號有沒有出現。但排列整齊還是值得多按幾下空白鍵，因為下一個編輯這份檔案的人，看到的是純文字。

GFM 表格的極限在哪裡

這套語法刻意做得很小。不能合併儲存格、不能巢狀表格，儲存格裡也放不了真正的換行。要顯示直線符號本身，得寫成 \|，否則會被當成欄位邊界；要在儲存格內換行，就得改用 <br> 標籤。

表格也是實務上最常出包的結構。跳脫規則、產生器，以及什麼時候該乾脆改用 HTML 表格，Markdown 表格指南都有完整說明。

待辦清單：在文件裡放核取方塊

待辦清單就是一般的項目清單，只是每一項以 [ ]（未完成）或 [x]（已完成）開頭。成敗取決於兩個空格：空方括號裡面要有一個，右方括號後面也要有一個。

## 發佈檢查清單

- [x] 更新變更記錄
- [x] 調升版本號
- [ ] 建立版本標籤
- [ ] 發佈版本說明
    - [ ] 巢狀子任務也支援

在 GitHub 上可以直接點選

待辦清單最強的地方，是它可以是互動的。在 Issue、Pull Request 描述與留言中，渲染出來的核取方塊可以直接點。你打勾的同時，GitHub 會替你改掉底層的 Markdown 原始碼。它還會顯示進度，例如 Issue 列表和引用該 PR 的地方都會出現「3 of 5 tasks」。Notion、Obsidian 和許多待辦事項應用程式，也把相同語法當成可點選的核取方塊。

其他地方是唯讀的方塊

在靜態輸出裡，方塊照樣會渲染出來，只是不能點。README、部落格文章、匯出的 HTML 檔都屬於這一類。發佈一份檢查清單仍然是對讀者最清楚的做法，因為他們可以直接複製原始碼再利用。

子任務走的是一般清單的縮排規則，所以一般清單的陷阱也照樣成立：子項目要縮排到父項目的文字下方，而且千萬不要把 Tab 和空格混著用。各家渲染器到底期待幾個空格，Markdown 清單語法寫得很清楚。

刪除線、自動連結與 HTML 過濾

還有三個比較小的擴充功能收尾。其中兩個是加語法，第三個則是刻意做減法。

刪除線：兩個波浪號

刪除線用兩個波浪號包住文字，~~像這樣~~ 就會渲染成劃掉的文字。它最適合誠實地呈現修正，例如 ~~$99~~ $79 讓舊價格仍然看得見。也可以用來標記某一行已經完成，而不必真的把內容刪掉。

自動連結：裸網址與電子郵件

自動連結省去了括號的麻煩。在原始 Markdown 中，直接貼上的網址如 https://mdeditor.tw 只是一段死文字，除非你用角括號或完整連結語法包起來。GFM 會自己認出裸網址與電子郵件地址，直接轉成可點擊的連結。

這在 Issue 留言裡是恩賜，在正式文件裡則是小陷阱。一串裸網址不會告訴讀者它通往哪裡，所以帶描述文字的寫法 [MD Editor](https://mdeditor.tw) 讀起來還是比較好。

禁用原始 HTML 標籤

原始 HTML 過濾是唯一做減法的擴充。Markdown 向來允許直接把 HTML 寫進文件，這正是 Markdown 與 HTML 比較那一頁的主題之一。但在一個有數百萬陌生人留言的平台上，這份自由就是安全漏洞。

因此 GFM 規格會過濾一份固定的危險標籤清單：<script>、<title>、<textarea>、<style>、<iframe>、<xmp>、<noembed>、<noframes>、<plaintext>。它會把開頭的角括號跳脫掉，讓標籤以文字形式出現而不會執行。一般排版用的 HTML，像 <br>、<sub>、<details>，仍然完全可用。

注意：這個過濾機制，就是你在自家部落格能用的影片嵌入碼，貼進 GitHub README 卻不見蹤影的原因。過程中不會有任何警告，那個 <iframe> 在渲染結果裡就是消失了。

程式碼區塊的語法上色

圍欄式程式碼區塊就是三個反引號、你的程式碼，再三個反引號，中間的內容會原封不動保留。真正讓那個灰色方塊變成彩色程式碼的，是語言代碼：緊接在開頭圍欄之後、中間不留空格的一個短字。

```python
def greet(name):
    print(f"Hello, {name}")
```

```js
const greet = (name) => console.log(`Hello, ${name}`);
```

GitHub 靠開源的語言辨識函式庫 Linguist 決定怎麼上色，也就是替每個儲存庫畫出語言比例條的那個元件。Linguist 認得數百種語言以及它們常見的別名，所以 py 和 python 會導向同一組上色規則。

萬一你寫了它不認得的代碼，不會壞掉，也不會跳出錯誤。那個區塊只會降級成普通的等寬程式碼區塊，就像你根本沒寫語言代碼一樣。圍欄還有幾條值得知道的規則，都整理在程式碼區塊語法那一頁。

你真正會用到的語言代碼

diff 區塊比文字描述更清楚

diff 值得單獨學起來。行首加 + 代表新增、加 - 代表刪除，GitHub 會把它們分別染成綠色與紅色：

```diff
- const port = 3000;
+ const port = process.env.PORT || 3000;
```

刻意關掉上色

另一個極端是 text，也可以寫成 plaintext。它的任務就是把上色關掉。終端機輸出、log 片段、目錄樹、ASCII 圖，都該用它。把上色器放進這些內容裡，它只會硬套上根本不存在的語法。

上色是渲染器的功能，不是 Markdown 的功能

這一點比表格裡任何一個代碼都重要。CommonMark 與 GFM 規格都沒有規定圍欄一定要上色。規格只說圍欄後面那串文字是「資訊字串（info string）」，渲染器可以自行運用。

實務上，那串文字會變成 <code> 元素上的 class="language-python"，接著由樣式表或上色函式庫接手。所以結果會因工具而異：

• GitHub 與 GitLab 會直接替你上色。
• 純 CommonMark 解析器不會，它本來也沒答應過要上色。
• 靜態網站產生器要先接上 Prism、highlight.js 或 Chroma 才會上色。

我們自己的線上編輯器也會上色，用的是 highlight.js，而且只在文件真的含有程式碼時才載入。有標語言代碼的圍欄會上色；沒標的則刻意維持素色，因為猜錯語言只會把程式碼染成錯的顏色。

小提醒：每個圍欄都標上語言代碼，連放終端機輸出的也一樣。寫 text 等於告訴下一個讀者「這塊本來就不該上色」，也避免日後某個工具猜錯。

用一般圍欄畫出 Mermaid 圖表

Mermaid 是 GitHub 對資訊字串最搶眼的運用。把圍欄標成 mermaid，GitHub 完全不會上色，而是把內容渲染成一張真正的圖：

```mermaid
graph TD;
  A[撰寫 Markdown] --> B[提交];
  B --> C[GitHub 渲染成圖表];
```

流程圖、時序圖、類別圖、狀態圖、甘特圖都能這樣寫。每一張都以純文字存在儲存庫裡，也像其他檔案一樣可以做版本比對。GitLab、Notion、Obsidian 同樣支援 Mermaid；不支援的渲染器則單純顯示成一般程式碼區塊。

上面那段不用離開本站就能試。把它貼進線上編輯器，預覽窗格就會把圖畫出來。萬一 Mermaid 語法打錯，那個圍欄會維持成程式碼區塊，不會跳錯誤訊息，所以寫到一半的圖不會拖垮整個預覽。

數學公式：$ 與 $$

GitHub 同樣支援 LaTeX 風格的數學式。行內公式放在單個錢字號之間，例如 $E = mc^2$；獨立展示的公式則放在各自成行的兩個錢字號之間：

$$
\frac{1}{n}\sum_{i=1}^{n} x_i
$$

GitHub 會在 README、Issue、留言與 Wiki 中用 MathJax 渲染這些公式。一般文句裡的錢字號可能被誤判成公式起點，所以要顯示錢字號本身時請寫成 \$。數學公式和語法上色一樣依賴渲染器：GitHub、Obsidian、Typora 與 Pandoc 都支援，純 CommonMark 解析器則會把錢字號原樣印出來。

本站的線上編輯器也會渲染數學公式，用的是 KaTeX。它接受 $行內$ 與 $$展示$$，也接受 LaTeX 使用者習慣打的 \(...\) 與 \[...\]。所以你可以先在這裡確認公式排出來對不對，再貼進 README。

GFM、CommonMark 與原始 Markdown 的差異

這三個名字經常被搞混，先把族譜理清楚：

• 原始 Markdown（2004）是 John Gruber 寫的 Perl 腳本，加上一份非正式的語法說明。開創性十足，但模糊到讓各家解析器為了邊界情況爭論了十年。
• CommonMark（2014）是嚴謹的標準化計畫。它用正式規格與數百個測試案例把每一處歧義釘死，而且刻意不新增任何功能。
• GFM（2017 年定稿）是 CommonMark 加上 GitHub 的擴充功能。這也是為什麼能解析 GFM 的工具，一定也能完美解析 CommonMark。

逐項比較

那到底該寫哪一種？

直接寫 GFM。它的降級表現很優雅：表格在只支援 CommonMark 的渲染器裡，頂多顯示成幾條直線符號，而不是壞掉的頁面。而且 GFM 正是你的同事、你的工具，還有未來的你最可能預期的方言。

例外情況是你無法掌控、也無法測試的目的地。不確定對方支援到哪裡時，就守住標題、清單、連結與強調這四樣，每種方言的處理方式都一致。我們的線上編輯器提供完整的 GFM 即時預覽，README、Issue 留言或 Wiki 頁面都能在發佈前先看清楚。