FormatArc CSV 轉 Markdown 表格的轉換結果，用於 GitHub READMEFormatArc CSV 轉 Markdown 表格的轉換結果，用於 GitHub README
作者: FormatArc 編輯部發布日期: 2026-09-02更新日期: 2026-09-02

GitHub README 表格製作指南：從 CSV 產生 Markdown Table

想在 README 中加入表格，最快的方式是把 CSV 資料貼到 CSV 轉 Markdown 並執行。整個過程在瀏覽器內完成，產出的表格符合 GitHub Flavored Markdown（GFM）格式，直接複製到 README 即可。

這篇文章整理 README 中適合用表格呈現的場面、從 CSV 或 JSON 自動產生的步驟，以及 GFM 表格容易出錯的注意事項。

README 何時需要表格

README 中如果只用純文字或項目符號排列資訊，行數一多就難以閱讀。下列類型的資料用表格呈現會直觀很多：

  • API 端點清單（路徑、HTTP 方法、說明）
  • 支援版本與平台的相容性對照表
  • 功能比較（本專案 vs 其他程式庫，或不同方案的差異）
  • CLI 命令選項參考
  • 環境變數清單與預設值

這些資訊用項目符號列出會越拉越長，而且無法橫向比較。改成表格後，讀者可以一眼掃過各欄找到差異，降低閱讀 README 的負擔。

實際 README 中的表格範例

上面提到的五種用途比較抽象，以下是可以直接貼到 README 的三個具體範例。

CLI 選項參考 — 當 flag 越積越多時，貼 --help 輸出不如用表格整理清楚。

| Flag | 預設值 | 說明 |
| :--- | :--- | :--- |
| `--port` | `3000` | HTTP 監聽埠號 |
| `--host` | `0.0.0.0` | 綁定位址 |
| `--log-level` | `info` | 日誌層級：`debug`、`info`、`warn`、`error` |

版本相容性對照表 — README 中最常被查閱的區塊，把支援的 runtime 用表格呈現一目了然。

| Runtime | 最低版本 | 驗證版本 | 狀態 |
| :--- | ---: | ---: | :--- |
| Node.js | 18.x | 22.x | LTS 正式支援 |
| Bun | 1.0 | 1.1 | 盡力支援 |
| Deno | 1.40 | 2.0 | 社群支援 |

與其他程式庫的功能比較 — 「為什麼要選這個程式庫」這段落幾乎必備。

| 功能 | 本專案 | 替代方案 A | 替代方案 B |
| :--- | :---: | :---: | :---: |
| 零依賴 | ✅ | ❌ | ✅ |
| TypeScript 型別 | ✅ | ✅ | ❌ |
| 瀏覽器環境可執行 | ✅ | ❌ | ❌ |

三個範例都控制在 3–4 列、3–4 欄，是刻意保持簡潔。這樣在 GitHub 的行動裝置畫面上不會出現橫向捲動，README 內容增加後仍可讀性維持不變。

Markdown 表格基本語法

GFM 表格用 pipe 符號 | 分隔欄位。

| 命令 | 說明 |
| --- | --- |
| install | 安裝相依套件 |
| build | 執行正式環境建置 |
| test | 執行測試 |

第一列是表頭，第二列是分隔列，第三列以後是資料列。在分隔列中加入冒號 : 可以指定對齊方式：:--- 靠左、:---: 置中、---: 靠右。

表格語法的細節在 Markdown 表格語法總整理 一文中有更完整的說明。

從 CSV 產生 README 表格

當資料在試算表或 CSV 檔案中時，用 CSV 轉 Markdown 來產生表格。

  1. 打開 CSV 轉 Markdown
  2. 在左側編輯區貼上 CSV 內容（從 Excel 或 Google 試算表複製的資料可以直接使用）
  3. 按下執行按鈕
  4. 把右側產生的 Markdown 表格複製到 README

CSV 轉 Markdown 表格的轉換結果CSV 轉 Markdown 表格的轉換結果

所有轉換都在瀏覽器內完成，即使貼上內部資料也不會傳送到任何外部伺服器。

轉換的機制與邊界情形，可參考 CSV 轉 Markdown 表格指南。如果還在考慮用哪一種格式管理表格資料，可參考 JSON、YAML、CSV、Markdown 資料格式比較速查表。

如果想在命令列中批次處理大量資料，可以搭配 formatarc npm 用 cat data.csv | formatarc csv-to-markdown 的方式輸出 GFM 表格，也能嵌入 CI 流程中自動更新 README。

從 JSON 資料建立表格

API 回應、日誌、設定 dump 等原始資料經常是 JSON 格式。最可靠的路徑是先轉成 CSV，再產生 Markdown 表格。想深入了解陣列、巢狀結構與 API 回應的表格化流程，可參考 JSON 轉 Markdown 表格。

步驟

  1. 用 JSON Formatter 格式化 JSON，確認資料結構
  2. 把 JSON 陣列轉為 CSV（每個物件的 key 變成欄位名稱，value 變成各列的儲存格）
  3. 把 CSV 貼到 CSV 轉 Markdown 產生表格

例如以下 JSON 陣列：

[
  { "name": "Node.js", "version": "20.x", "status": "LTS" },
  { "name": "Node.js", "version": "22.x", "status": "Current" }
]

轉成 CSV 後：

name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current

把這份 CSV 貼到 CSV 轉 Markdown，就能得到可直接貼到 README 的表格。

README 表格常見的 4 個問題

README 中表格「壞掉」的原因通常集中在四種。先確認是哪一種，就不用花大量時間逐行除錯。

在開始之前先釐清一點：GFM 規格 4.10 節定義分隔列為「內容僅為連字符（-），選配地在前後加上冒號（:）的儲存格」，並未規定連字符的最少數量，也並未要求表格上方必須有空行。

欄位數不匹配

分隔列決定了表格的總欄數。超過分隔列欄數的儲存格會被無聲地丟棄，不足的列則補上空白儲存格。

| name | role |
| --- | --- |
| Alice | Engineer | LA      ← 多出的儲存格無預警被忽略
| Bob                        ← 不足的儲存格以空白渲染

GitHub 不會顯示任何警告。如果表格右側的欄莫名其妙是空的，先數一下該列的 pipe 數量。

分隔列遺漏或格式錯誤

把文字區塊變成表格的關鍵就是分隔列。分隔列寫錯，整段就無法被識別為表格。重點在欄位數是否一致，而不是連字符的數量。

| name | role |
| --- |            ← 表頭 2 欄但分隔列只有 1 欄，任何 parser 都不會識別為表格
| Alice | Engineer |

這個案例在 4 個 parser 上驗證過（scripts/benchmarks/markdown-table-parsers/，2026-07-15 實測。GitHub Markdown API、marked 18.0.5、remark-gfm 4.0.1、strict CommonMark remark-parse）。欄位數不一致時，4 個 parser 全部無法渲染為表格。

連字符數量則是另一回事。同一組實測中，| - | - | 和 | -- | -- | 在 GitHub Markdown API、marked、remark-gfm 上都能正常渲染為表格。三個連字符（---）只是可讀性的慣例，不是必要條件。GitHub 自己的文件寫「3 個以上」，但規格未做規定，實作上 1 個就接受。所以表格渲染不出來時，先數連字符是錯誤的出發點。更多症狀別的診斷與修正方法，可參考 Markdown 表格壞掉的原因。

不過分隔列過短確實有一個例外。如果省略外側 pipe 且連字符只寫 1 個（- | -），GitHub 會把這段解讀為列表。

h1 | h2
- | -              ← GitHub 會渲染成列表；寫 `--- | ---` 則是表格
a | b

編輯器中看得到但 GitHub 上看不到時，先確認分隔列的欄位數，再確認外側 pipe 是否存在。

GitHub 與編輯器的空白儲存格差異

GFM 允許完全為空的儲存格。

| 功能 | Basic | Pro |
| :--- | :---: | :---: |
| PDF 匯出 |  | ✅ |
| API 存取 |  | ✅ |

GitHub 能正確渲染空白儲存格，但部分 Markdown 編輯器會把連續的 pipe 視為語法錯誤，導致該列顯示異常。Markdown 原始碼本身沒問題，是編輯器的預覽不正確。最終以 GitHub 上的渲染結果為準。

儲存格內的 pipe | 需要轉義

儲存格中如果直接寫 pipe 符號，會被當成欄位分隔符，表格就會斷裂。用反斜線轉義（\|）或使用 HTML entity |。

| 條件式 | 意義 |
| --- | --- |
| `a \| b` | 位元 OR |
| `a | b` | entity 寫法 |

GitHub 上兩種寫法都會正確渲染為 a | b。反斜線轉義是 GFM 標準寫法，但如果 README 會經過 Hugo 或 MkDocs 等非 GFM 工具鏈處理，entity 寫法更穩妥。

GFM 表格的注意事項

GitHub 的 Markdown 渲染器跟一般編輯器有幾處不同的行為。

儲存格內換行用 <br>

GFM 表格規格不支援儲存格內的實體換行。即使寫成多行，渲染時仍會合併為一行。

| 步驟 | 說明 |
| --- | --- |
| 1 | 安裝相依套件
並執行建置 |

如果需要儲存格內換行，使用 <br> 標籤。GitHub 會把它當作儲存格內的換行處理。

| 步驟 | 說明 |
| --- | --- |
| 1 | 安裝相依套件<br>並執行建置 |
| 2 | 執行測試<br>提交 lockfile |

<br> 是 GitHub Markdown sanitizer 在表格儲存格內允許的少數 HTML 標籤之一。

儲存格內的格式：強調、程式碼、連結、badge

儲存格內部的 inline Markdown 完全有效。README 表格常被用來做狀態表或對照表，原因就在這裡。粗體、inline code、連結、圖片、表情符號都能渲染。

| Package | 建置狀態 | 文件 |
| --- | --- | --- |
| `core` | ![build](https://img.shields.io/badge/build-passing-brightgreen) | [閱讀](./docs/core.md) |
| `cli` | :warning: experimental | [閱讀](./docs/cli.md) |

但有兩樣東西不行。第一是 block 層級元素：標題、項目列表、fenced code block 都不能放進儲存格。儲存格開頭的 # 會原樣顯示為 # 字元。第二是 pipe 符號：shields.io 的 URL 或圖片連結中如果包含 |，儲存格會在那裡斷裂。?label=a|b 這類 query string 需要把 pipe 轉義為 \| 或 percent-encode 為 %7C。

從 CSV 或 JSON 自動產生表格時，如果把 badge 的 Markdown 寫在原始資料的儲存格中，CSV 轉 Markdown 會原樣保留，重新產生時 badge 欄不會消失。

HTML 標籤混用限制

GitHub 出於安全考量，嚴格限制表格儲存格內的 HTML 樣式。<br> 可以用作換行，但 <span style="...">、<font color> 這類 inline style 會被忽略。儲存格內無法自訂字體顏色或大小。<details> 這類 block 層級標籤在表格外部有效，儲存格內則無效。

欄對齊指定

分隔列加冒號的對齊語法在 GitHub 上正常運作。把數字欄（版本號、價格、統計值）設為右對齊（---:），對齊後可讀性大幅提升。

| 方案 | 月費 |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |

寬表格與橫向捲動

欄數多的表格在 GitHub 上會觸發橫向捲動。如果讀者會在桌面與行動裝置兩種環境閱讀 README，建議把欄數控制在 5–6 欄以內，或依性質拆成多個表格。

常見問題

README 的表格可以用試算表管理嗎？

可以。在 Google 試算表或 Excel 中維護表格資料，內容更新時匯出 CSV，再用 CSV 轉 Markdown 轉換，就能隨時把最新狀態的表格反映到 README。

表格儲存格能放連結或圖片嗎？

可以。儲存格內用 [連結文字](URL) 格式寫 Markdown 連結，或用 ![替代文字](圖片 URL) 放圖片，GitHub 上都會正常渲染為可點選的連結與圖片。

總結

  • README 加入表格後，複雜的選項、版本相容性、功能比較等資訊都能直觀呈現
  • Markdown 表格由 pipe | 和分隔列的連字符 - 組成，用冒號 : 指定對齊方式
  • 表格斷裂的主因是表頭與分隔列的欄位數不一致，以及儲存格內的 pipe（|）未轉義，而非連字符數量
  • 資料列多或結構複雜時，用 CSV 轉 Markdown 從 CSV 自動產生，比手動輸入 pipe 快速且不易出錯