TL;DR — GFM 表格快速參照
GFM（GitHub Flavored Markdown）表格是以管線 | 分隔的表格，定義於 GitHub 規格中，不屬於 CommonMark 核心規格。
- 表格由標題行、分隔行（
---，每欄慣例用 3 個連字號）、資料行組成，以管線|分隔。表格前後必須有空行。 - 對齊由分隔行中冒號的位置決定：
:---左對齊 /:---:置中 /---:右對齊。 - 儲存格內的管線用反斜線跳脫為
\|；在跳脫失效的環境中可用 HTML 實體|作為備援。 - 儲存格內換行直接寫
<br>。GitHub 和 GitLab 上正常運作，Obsidian、Notion 等工具則取決於編輯模式或匯入路徑。 - 儲存格合併（rowspan/colspan）、多段落、程式碼區塊等區塊元素無法在 GFM 表格中使用。需要時改用 HTML
<table>。 - 不想手打管線的話，把 CSV 資料貼到 CSV 轉 Markdown 就能立即產生 GFM 相容表格。
本文是給已經會寫 Markdown 表格、想快速確認語法細節的人用的速查卡。如果你想從零開始學習表格的寫法，建議先看基本的 Markdown 表格教學。
GFM 表格能與不能
| 可以做到的事 | 無法做到的事 |
|---|---|
| 標題行 + 資料行的表格 | 沒有標題行的表格（標題行是必需的） |
| 每欄的左對齊、置中、右對齊 | 以數值指定欄寬（px、%） |
| 儲存格內的行內格式（程式碼、連結、圖片、強調、刪除線） | 儲存格內的程式碼區塊、清單、多段落（區塊元素） |
用 <br> 達到視覺換行（取決於環境） | 跨列或跨欄的儲存格合併（rowspan / colspan） |
| 管線及特殊字元的跳脫 | 表格內的標題（#）或引用區塊（>） |
需要區塊元素或儲存格合併時，直接寫 HTML <table> 標籤，而不是硬塞進 Markdown 表格。
基本結構 — 最小對照
GFM 表格由三個部分組成：標題行、分隔行、資料行。分隔行的連字號慣例上每欄用 3 個（GFM 規格未規定最低數量），行首行末的管線可以省略。
語法：
| 姓名 | 權限 |
| --- | --- |
| 張小明 | admin |
| 李小花 | viewer |
渲染結果：
| 姓名 | 權限 |
|---|---|
| 張小明 | admin |
| 李小花 | viewer |
最小的表格（標題 1 行 + 資料 1 行）長這樣：
| key | value |
| --- | --- |
| name | FormatArc |
對齊語法速查
分隔行中冒號（:）的位置決定該欄的對齊方式。
| 寫法 | 對齊方式 |
|---|---|
:--- | 左對齊（與沒寫冒號時相同） |
:---: | 置中對齊 |
---: | 右對齊 |
語法：
| 商品 | 數量 | 單價 |
| :--- | :---: | ---: |
| 蘋果 | 3 | 120 |
| 柳丁 | 10 | 80 |
渲染結果：
| 商品 | 數量 | 單價 |
|---|---|---|
| 蘋果 | 3 | 120 |
| 柳丁 | 10 | 80 |
數值欄右對齊可以讓數字位數整齊，閱讀時更容易比較大小。
儲存格內可用的格式
儲存格內可以使用行內元素。程式碼區塊、項目清單、多段落等區塊元素則不能使用。
| 想表達的內容 | 語法（寫在儲存格內） | 渲染結果 |
|---|---|---|
| 行內程式碼 | `npm run build` | npm run build |
| 連結 | [FormatArc](https://formatarc.com/) | FormatArc |
| 圖片 |  | （圖片會顯示出來） |
| 強調 | *斜體* / **粗體** | 斜體 / 粗體 |
| 刪除線 | ~~刪除線~~ | |
| 換行 | 第一行<br>第二行 | 第一行 第二行 |
儲存格裡放圖片可以，但會讓表格變得很高、版面容易錯亂，實務上控制在小圖示的大小比較安全。
空白儲存格的寫法
把儲存格留空是合法的語法。管線之間不寫任何內容，該儲存格就會渲染為空白。
語法：
| 姓名 | 權限 | 備註 |
| --- | --- | --- |
| 張小明 | admin | |
| 李小花 | | viewer |
渲染結果：
| 姓名 | 權限 | 備註 |
|---|---|---|
| 張小明 | admin | |
| 李小花 | viewer |
處理空白儲存格時有兩點要注意：
- 欄數必須與標題行一致。空白儲存格是
| |（兩個管線之間留空），不是省略管線。少一個管線就少一欄，整張表格會對不齊。 - 如果某行的第一個儲存格是空的、而且行首的管線也省了，部分渲染器會把該列的第一欄當作缺失。保留行首的
|（寫成| | 值 |），或在第一個儲存格放空連結[]()作為保險，都可以防止欄位遺失。
空白儲存格不是儲存格合併。GFM 沒有 rowspan 或 colspan，空白就是空白，不會與上方或旁邊的儲存格視覺上合併。需要合併的話要改用 HTML <table>。
管線與特殊字元跳脫速查
儲存格裡直接寫 | 會被解析器當作欄位分隔符，表格版面就壞了。安全的寫法有兩種：
| 方式 | 寫法 | 相容性與特性 |
|---|---|---|
| 反斜線跳脫 | cmd1 | cmd2 | GitHub、GitLab、Notion、Obsidian 等主要 GFM 渲染器都支援（GitHub 官方規格有說明） |
| HTML 數字字元參考 | cmd1 | cmd2 | 渲染器不正確處理 | 時的備援。跨編輯器複製貼上較不易損壞 |
語法：
| 指令 | 說明 |
| --- | --- |
| cmd1 \| cmd2 | 用反斜線跳脫 |
| cmd1 | cmd2 | 用 HTML 實體表示 |
渲染結果：
| 指令 | 說明 |
|---|---|
| cmd1 | cmd2 | 用反斜線跳脫 |
| cmd1 | cmd2 | 用 HTML 實體表示 |
除此之外，想顯示反斜線本身就用 \\，想放不換行的空白就用 。從 CSV 或 HTML 產生 Markdown 表格時，CSV 轉 Markdown 會自動處理管線跳脫，不用手動處理。
儲存格內換行與各平台支援狀況
Markdown 表格規格中，儲存格內無法直接用鍵盤 Enter 換行。要在儲存格內產生視覺換行，必須直接寫 HTML 標籤 <br>。但各平台的支援程度不同：
| 平台 | 儲存格內 <br> 換行 | 備註 |
|---|---|---|
| GitHub | 支援 | 官方文件中有說明 |
| GitLab | 支援 | 官方文件明確列出可用於儲存格內換行 |
| Obsidian | 大致支援 | 即時預覽與閱讀模式的渲染效果可能不同 |
| Notion | 取決於匯入路徑 | 以 Markdown 匯入時會轉為 Notion 自己的表格區塊，<br> 可能不會變成換行 |
| 部落格平台 | 大多支援 | 取決於該平台的 Markdown 渲染器規格 |
如果一張表有很多欄都需要可靠換行，與其硬塞進 GFM 表格，不如改用 HTML <table> 或把欄拆開。
表格壞掉的原因與檢查清單
表格沒有正確渲染、直接顯示成文字時，依序檢查以下項目：
- 表格前後有沒有空行 — 與前後文字緊貼時，解析器可能不把它當成表格（GitHub 上特別容易遇到）
- 有沒有標題行 — GFM 要求標題行必須存在。即使不想顯示標題文字，也要寫一個空的標題行加分隔行
- 標題行與分隔行的欄數是否一致 — 不一致時表格完全不會被辨識。連字號的個數（
--或---）不是問題所在 - 標題行、分隔行、資料行的欄數（管線數量）是否一致 — 資料行欄數不足會補空白儲存格，多出來則被截斷
- 儲存格內有沒有未跳脫的管線
|— 有的話改成\|或| - 行首有多餘的縮排（4 個以上空格）嗎 — 會被誤認為程式碼區塊
- 儲存格內有沒有放程式碼區塊或項目清單等區塊元素 — GFM 表格不允許
檢查清單解決不了的問題，通常是渲染器本身不支援 GFM 表格擴展（純 CommonMark 環境）。如果問題不在上述清單中，可參考 Markdown 表格語法錯誤：症狀別診斷與修正 進一步診斷。
從 CSV / HTML / JSON 自動產生表格
5 行以內的小表格手寫還好，但超過 20 行或欄數很多時，手動對齊管線和跳脫很容易出錯。根據原始資料的格式，可以用 FormatArc 的轉換工具一步生成 GFM 相容表格：
- CSV / 試算表 / Excel 資料：貼到 CSV 轉 Markdown 執行，立即得到管線表格。詳細步驟見 CSV 轉 Markdown 表格指南。
- 既有 HTML（網頁上的表格、Notion 匯出、CMS 的資料 dump）：把 HTML 貼到 HTML 轉 Markdown 工具，
<table>標籤會被提取為管線表格。詳細見 HTML 轉 Markdown 指南。 - JSON（API 回應或日誌資料）：先轉成 CSV，再以 CSV 轉 Markdown 產生表格。每個物件的 key 作為欄名、值作為各列的儲存格內容。完整轉換見 JSON 轉 Markdown 表格。
所有處理都在瀏覽器內完成，內部資料或客戶名單貼上去也不會傳到外部伺服器。不需要註冊，不需要上傳檔案。
產生的表格如果要傳給 LLM 當 prompt，Markdown 表格比同等內容的 HTML 更節省 token，模型提取行列關係的準確度也較高。實測的 token 對比見 LLM Markdown vs HTML。
Markdown 表格做不到的事 — 何時該用 HTML
以下需求的表格在 GFM 表格中無法表達，要直接寫 HTML <table> 標籤：
- 跨列或跨欄的儲存格合併（
rowspan/colspan） - 儲存格內需要放項目清單、多段落、程式碼區塊
- 要以像素或百分比固定欄寬
- 表格內要嵌套標題或另一張表格
不過要注意，GitHub 等平台出於安全考量會限制表格內的 HTML。<br> 可以通過，但 <span style="..."> 的 style 屬性會被整個移除（<span> 本身保留），所以改顏色或字體大小是做不到的。
為什麼 GFM 不支援儲存格合併（rowspan / colspan）
GFM 規格的 Tables (extension)在新分頁中開啟 在 ABNF 層級要求「1 行 = 1 row」的結構，從語法上沒有空間表達跨行的儲存格合併。這是優先考慮文字可讀性與解析器實作簡單度的設計決策，之後 CommonMark 的表格擴展討論也延續了同樣的方向。需要合併的表格，就把它視為超出 GFM 範圍的需求，改用 HTML <table> 來處理。
用 HTML <table> 做合併的最小範例
在 Markdown 檔案中直接寫 HTML，GitHub 等 GFM 渲染器會把它當作 HTML 表格來渲染。
欄方向合併（colspan）：
<table>
<tr><td colspan="2">期間（2026）</td></tr>
<tr><td>4 月</td><td>9 月</td></tr>
</table>
列方向合併（rowspan）：
<table>
<tr><td rowspan="2">專案 A</td><td>啟動</td></tr>
<tr><td>交付</td></tr>
</table>
GitHub 保留與移除的 HTML 屬性
GitHub 會出於安全目的 sanitize 表格內的 HTML，不在允許清單中的屬性會被整個移除。下表是用 GitHub 的 Markdown 渲染 API（與 README 和 issue 正文相同的管線）實測的結果，測量腳本與原始輸出在儲存庫的 scripts/benchmarks/github-table-attributes/ 中。
| 屬性 | 實測結果 | 說明 |
|---|---|---|
colspan / rowspan | 保留 | 可以安全用於儲存格合併 |
align（td/th） | 保留 | 可以覆寫每欄的水平對齊 |
valign（td/th） | 保留 | 可以指定垂直對齊位置 |
width / height（td） | 保留 | width="50%" 和 width="120px" 都會保留（值本身不會被檢查） |
id | 值被改寫 | id="foo" 變成 id="user-content-foo"（屬性保留，但你寫的值無法直接錨定連結） |
class | 移除 | 屬性整個消失 |
style（行內樣式） | 移除 | 文字顏色、背景色、字體大小都無法設定 |
bgcolor | 移除 | 屬性整個消失 |
<script> / on* 事件處理 | 移除 | 為防止 XSS 而全面移除 |
如果想用顏色或字體大小強調特定儲存格，可以改用表格外的徽章或圖示、用 Markdown 的 **粗體** 代替、或把表格截圖後以圖片貼上。
GFM 以外的儲存格合併擴展語法（GitHub 上不支援）
以下語法在 GitHub 上不會渲染，但在本地 Markdown 預覽或特定工具中可以使用：
- VS Code 外掛 Markdown Preview Enhanced在新分頁中開啟 —
>與上方儲存格合併，^與左方儲存格合併 - Python-Markdown 外掛 mdx_tableau在新分頁中開啟 — 在 Markdown 語法中寫 colspan/rowspan
- Pandoc grid table / multiline table在新分頁中開啟 —
+---+---+格線格式可表達合併
如果目標是 GitHub README 或 Issue 正文，最安全的做法還是直接寫標準 HTML <table>，不依賴這些工具專屬的擴展。
CommonMark 與表格的關係
純 CommonMark在新分頁中開啟 規格中沒有表格語法的定義。管線分隔的表格是 GitHub Flavored Markdown 規格中 Tables (extension) 節在新分頁中開啟 定義的 GFM 專屬擴展。因此，只實作 CommonMark 核心而不含表格擴展的解析器會把 | col | 當成一般文字顯示，而不是表格。想確認你使用的環境是否支援 GFM 表格，最快的方式就是寫一張 3 行的簡單表格看它有沒有渲染出來。
常見問題
最小的 Markdown 表格怎麼寫？
共 3 行：標題行 1 行、分隔行 1 行、資料行 1 行。先寫 | key | value |，下面寫 | --- | --- |，再下面寫 | name | FormatArc |。分隔行的連字號慣例用 3 個（---），但 GFM 規格上 1 個也有效。
怎麼把儲存格留空？
兩個管線之間不寫任何內容就是空白儲存格（| 值 | |）。欄數必須與標題行一致，所以空白儲存格是 | | 而不是省略管線。如果空白儲存格在行的最前面，一定要保留行首的管線（| | 值 |），否則部分渲染器會把第一欄丟掉。空白儲存格不是儲存格合併，GFM 沒有 rowspan 或 colspan。
\| 和 | 該用哪個？
先用反斜線跳脫 \|。這是 GitHub 官方文件說明的寫法，主要 GFM 渲染器都能正確處理。只有當渲染器不正確處理 \|、或跨編輯器複製貼上時字元會損壞的情況，才改用 | 作為備援。
儲存格內能改文字顏色或字體大小嗎？
只靠 GFM 表格做不到。GitHub 等平台會移除表格內的 style 屬性，所以寫 <span style="..."> 也不會有顏色或大小的變化。如果一定要裝飾，考慮把表格移出改用 HTML，或換一種呈現方式。
欄寬有沒有建議？
Markdown 沒有指定欄寬的語法，渲染器會依內容長度自動調整。實務上，如果 README 或文件會同時在桌面和手機上閱讀，建議把欄數控制在 5～6 欄以內。超過這個數量在 GitHub 上會出現水平捲動，讀起來很吃力。
能做儲存格合併（rowspan / colspan）嗎？
GFM 表格做不了。需要合併的表格要直接在 Markdown 中寫 HTML <table>。但 GitHub 等平台會限制部分 HTML 屬性，寫完後要先確認渲染結果再上線。
表格沒有渲染，直接顯示 | col | 文字。為什麼？
常見原因：表格前後沒有空行、缺少標題行、標題行與分隔行的欄數不一致、或渲染器不支援 GFM 表格擴展（純 CommonMark 環境）。請依上方「表格壞掉的原因與檢查清單」從上到下逐項排查。
總結
GFM Markdown 表格是用管線（|）和連字號（-）來簡潔表達表格的工具。記住對齊指定、管線跳脫、空白儲存格處理這幾個基本規則，寫 GitHub README 或文件時就能輕鬆產出整齊的表格。
行數多或要處理複雜的試算表資料時，用 CSV 轉 Markdown 轉換器自動產生表格，可以有效減少輸入錯誤和耗時。