想在 GitHub README 中放入功能比較表、在 Issue 或 Pull Request 中分享測試結果、或者把試算表資料整理到 Notion 和 Obsidian，這些場景都需要把 CSV 資料轉成 Markdown 表格。
從 Excel 或 Google 試算表複製的表格直接貼到 Markdown 中不會變成表格格式，手動輸入 | 並對齊欄位寬度，行數一多就非常繁瑣。
如果需要立刻取得轉換結果，把 CSV 貼到 CSV 轉 Markdown 並按下執行按鈕，即可立即產生 GitHub 相容的 Markdown 表格。如果想先了解 Markdown 表格的語法結構和常見陷阱，請繼續閱讀。
轉換時發生了什麼
先從要貼上的 CSV 資料開始看起。
name,email,role
Mika,mika@example.com,admin
Noah,noah@example.com,viewer
將這組資料通過轉換工具後，會得到以下的 Markdown 表格：
| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |
第一列的標題行直接成為 Markdown 表格的表頭，其下自動插入分隔列，剩餘每一列則轉換為前後加上 | 的資料行。基本的轉換原理就是這樣，實務上遇到的問題几乎都是輸入資料不像上面這麼乾淨時才會出現。
Markdown 表格的基本結構
GitHub Flavored Markdown（GFM）的表格使用 | 作為欄位分隔符，如上例所示。
第一列是表頭，第二列是分隔線，第三列開始是資料行。分隔線中 : 的位置決定對齊方式：左對齊、置中、右對齊。
| 左對齊 | 置中 | 右對齊 |
| :--- | :---: | ---: |
| a | b | c |
語法本身很直覺，但行數和欄數一多就難以手動維護。20 行 5 欄的表格，要讓每一欄的 | 位置都對齊，手動輸入實在不值得花這個時間。
手動轉換 CSV 為什麼費工
只有三四行的話還能手寫，但實務上用到的表格通常會遇到以下問題：
- 行數多（一開始只有 5 行的比較表，項目不斷增加）
- 儲存格內含
|符號，需要跳脫處理 - 儲存格內含換行，無法塞進 Markdown 表格的單行中
- 各行列數不一致的 CSV 直接貼上會導致表格結構錯亂
特別是從 Excel 匯出的 CSV，數字中的千位分隔逗號（如 1,000）會被誤認為欄位分隔符，或者因為換行字元的差異導致排版錯亂。
轉換方式比較
把 CSV 轉成 Markdown 表格的方法不只一種。適合哪種取決於資料量和你的工作环境。
| 轉換方式 | 初始設定 | 外部伺服器傳輸 | 大量行處理 | | 自動跳脫 |
| --- | --- | --- | --- | --- |
| 瀏覽器工具（FormatArc） | 不需要 | 無（本機執行） | 優 | 自動處理 |
| CLI 工具（csvtomd / csv2md 等） | 需 pip / npm 安裝 | 無 | 優 | 因工具而異 |
| 手動撰寫 | 不需要 | 無 | 不實際 | 手動處理 |
| awk / sed 腳本 | 需 shell 與正規表達式知識 | 無 | 普通 | 自行實作 |
CLI 工具方便整合到 CI/CD 或自動化管線中，但需要安裝執行環境。手動撰寫對幾行的小表格還行，行數一多就無法維護。瀏覽器工具不需要任何安裝，貼上的資料不會傳送到外部伺服器，| 的跳脫也自動處理。處理敏感業務資料時，比上傳到伺服器的線上轉換服務更安全。
用 FormatArc 把 CSV 轉成 Markdown 表格
使用 CSV 轉 Markdown 只需貼上 CSV 資料並按下按鈕，即可得到 GFM 相容的 Markdown 表格。
步驟 1：開啟工具
前往 CSV 轉 Markdown 頁面。
步驟 2：貼上 CSV
在左側輸入區貼上 CSV 資料。從 Excel 或 Google 試算表複製範圍後貼上，或直接使用純文字檔案的內容都可以。第一列會自動識別為標題列。
步驟 3：按下執行
按下執行按鈕後，右側立即顯示 Markdown 表格。
輸出結果可以直接複製貼到 GitHub README、Issue、PR 或部落格正文中。分隔線和欄位寬度會自動對齊。
所有轉換處理都在瀏覽器分頁內以 JavaScript 執行，貼上內部文件或客戶名單也不會傳送到外部伺服器。
轉換時常遇到的問題與解法
儲存格內的 | 符號
如果儲存格內容包含 |，Markdown 解析器會將其誤認為欄位分隔符。FormatArc 會自動將儲存格內的 | 跳脫為 \| 輸出，不需要手動修改。
| x | y |
| --- | --- |
| foo\|bar | baz |
儲存格內的換行
Markdown 表格的標準規格沒有表達儲存格內多行文字的語法。FormatArc 會將儲存格內的換行替換為一個空格，維持表格結構。如果需要在儲存格內顯示換行，必須在原始資料中直接插入 HTML <br> 標籤。
各行列數不一致（不平整行）
標題列有 3 欄但資料列有 4 欄的 CSV，會以標題列的欄數為基準，多出的第 4 欄被截斷。反之，如果資料列的欄數不足，則以空白儲存格補齊，確保表格結構不破裂。
雙引號包裹的欄位
CSV 欄位用雙引號包裹時，內部包含逗號也會被視為單一儲存格。例如 "Taipei, Taiwan" 是 1 欄而非 2 欄。雙引號屬於 CSV 語法的一部分，不會出現在轉換後的 Markdown 結果中。
name,location,note
Mika,"Taipei, Taiwan","said ""ok"" twice"
| name | location | note |
| --- | --- | --- |
| Mika | Taipei, Taiwan | said "ok" twice |
雙引號欄位內的連續 "" 是 CSV 的跳脫規則，代表一個字面上的雙引號（"）。因此 note 欄輸出的是純雙引號。如果轉換結果中出現多餘的引號，或一個值被拆成兩欄，通常不是轉換器的問題，而是原始 CSV 的引號使用有語法錯誤。
轉換後 Markdown 表格的實務應用
GitHub README
API 端點清單、支援的選項參數、開源函式庫功能比較表，README 中需要表格的場合非常多。用 CSV 或試算表管理原始資料，資料更新時重新轉換一次即可，不需要每次手動重繪表格。
Issue 與 Pull Request
效能測試數據、回歸測試結果矩陣、設計決策比較表，以表格形式呈現會讓 code reviewer 更容易快速掌握變更內容。在試算表中整理好後轉為 Markdown 表格直接貼上即可。
Notion、Obsidian 與其他支援 Markdown 的工具
這些工具都支援 Markdown 或能處理 Markdown 表格的貼上。用 CSV 管理資料，需要時再轉為 Markdown 表格，跨平台搬移時就不必重新整理格式。
LLM（ChatGPT、Claude、Gemini）的上下文傳遞
把表格資料傳給 LLM 時，用 Markdown 表格比原始 HTML <table> 更有效率。不僅 token 消耗較少，模型也能更準確地提取行列關係進行推理。
各渲染器的對齊（alignment）支援狀況
GFM 對齊語法（:--- 左對齊、:---: 置中、---: 右對齊）在開發者導向的平台上支援良好，但部分服務和 CMS 會忽略對齊或只部分支援。如果表格的對齊看起來跟預期不同，可以參考以下各平台的支援狀況。依據為「官方文件」的項目基於平台公開規格，「使用者回報」的項目為廣泛觀測到的行為，重要文件建議先用 2 行左右的樣本表格到目標平台貼上確認。
| 平台 | :---（左） | :---:（中） | ---:（右） | 儲存格合併（colspan/rowspan） | 依據 |
|---|---|---|---|---|---|
| GitHub README / Issue / PR | 支援 | 支援 | 支援 | 不支援（需 HTML） | 官方文件（GFM 規格 tables extension在新分頁中開啟) |
| GitLab | 支援 | 支援 | 支援 | 不支援 | 官方文件（GitLab Markdown docs在新分頁中開啟) |
| Bitbucket | 支援 | 部分支援 | 支援 | 不支援 | 使用者回報 — 建議在個別環境確認 |
| Notion（貼上匯入） | 支援 | 忽略 | 忽略 | 不支援 | 使用者回報 — 建議用樣本貼上確認 |
| Obsidian | 支援 | 支援 | 支援 | 不支援（需 HTML） | 官方文件（Obsidian 說明 tables在新分頁中開啟) |
| VS Code 預覽 | 支援 | 支援 | 支援 | 不支援（HTML 儲存格可以） | 官方文件（內建預覽使用 markdown-it + GFM tables） |
如果需要儲存格合併或複雜的格線佈局，直接在 Markdown 中嵌入純 HTML <table> 標籤是最務實的解法。大多數 Markdown 渲染器都能正常顯示內嵌的 HTML 表格。
文字編碼與分隔符號自動偵測
CSV 不是單一的格式，會因編碼（UTF-8、UTF-8 BOM、Big5、Windows-1252 等）和分隔符號（逗號、分號、Tab、直線）的不同而表現差異很大。需要確認的重點有兩項：
- 文字編碼 — CSV 轉 Markdown 工具採貼上方式，處理的是瀏覽器已經解碼的字串。UTF-8（含或不含 BOM）的檔案用任何現代文字編輯器打開複製即可正常運作。Big5 或 CP950 儲存的舊版 Excel CSV 檔案，必須先用編輯器（VS Code 的「以編碼重新開啟」）以正確編碼打開後再複製，否則繁體字會變成亂碼。
- 分隔符號自動偵測 — 工具會自動判斷
,、;、\t、|。歐洲地區因為小數點使用逗號，CSV 常用分號（;）作為欄位分隔。分號分隔的 CSV 直接貼上也能正常識別。如果同一檔案中分隔符號混雜且模稜兩可，請在原始程式中統一分隔符號後再匯出。
常見問題
沒有存成 CSV 檔案，直接從 Excel 複製貼上也行嗎？
可以。從 Excel 或 Google 試算表拖選範圍複製時，剪貼簿中存放的是 Tab 分隔的文字（TSV），不是逗號分隔的 CSV。CSV 轉 Markdown 工具會自動偵測 Tab 分隔符並正確轉為 Markdown 表格。
FormatArc 會把貼上的 CSV 上傳到伺服器嗎？
不會。所有轉換處理完全在你的瀏覽器分頁內以 JavaScript 執行，FormatArc 伺服器或任何外部伺服器都不會收到你的資料。包含內部機密資料、客戶資訊、NDA 文件的 CSV 都可以安全轉換。
GitHub 上顯示正常但其他平台表格破裂
很可能是該平台的 Markdown 渲染器不支援 GFM 表格語法或對齊擴充。Notion 會用自己的區塊樣式覆蓋對齊設定，部分舊版 CMS 或僅支援 CommonMark 的渲染器會完全忽略直線表格，當成純文字顯示。這類平台建議將表格轉為 HTML <table> 後再插入。
儲存格內的 | 如何跳脫？
使用 \|（反斜線 + 直線）。FormatArc 的轉換工具會自動處理貼上的 CSV 中包含的 | 字元，不需要手動跳脫。
貼上的資料大小或行數有限制嗎？
在瀏覽器分頁記憶體容許的範圍內沒有硬性限制。工具內執行轉換的程式碼經過基準測試（scripts/benchmarks/csv-to-markdown-throughput/，2026-07-13 在 Apple M5 Pro、Node 環境下 warm 7 次測量的中位數），10,000 行的 CSV 約 7 毫秒、50,000 行約 36 毫秒、100,000 行（約 5MB）約 75 毫秒即可完成轉換。一般瀏覽器環境中，轉換運算本身幾乎不會成為瓶頸。如果要處理數百 MB 的超大資料，建議用本機腳本處理而非直接貼到瀏覽器分頁中。
總結
把 CSV 資料轉成 Markdown 表格，手動操作要處理行數計算、| 位置對齊、特殊字元跳脫，花掉大量時間。使用 CSV 轉 Markdown 工具只需貼上資料按一個按鈕，就能完成 GitHub 相容的 GFM 表格。
如果需要對產生的 Markdown 表格做更細部的調整（對齊設定、| 跳脫、換行處理、GFM 細節注意事項），建議直接參考 GFM 官方規格。CSV 格式的基本概念、以及把 CSV 轉為 JSON 的操作方式，也是日常工作中常用的搭配。