為什麼表格是 Markdown 最難搞的部分
- 表格需要三個部分：標題列、由破折號組成的分隔列，以及資料列。
- 分隔列裡的冒號決定整欄的對齊方式，無法只對齊單一儲存格。
- 儲存格只吃行內語法。不能換行、不能放清單、不能放程式碼區塊。
- 儲存格裡若有真正的管線符號，必須寫成
\|跳脫，否則會把格子切成兩半。
表格是後來才加上去的
大部分 Markdown 語法都很寬容，少個空格，渲染器常常會自己補救。表格不一樣。它根本不在 2004 年的原始規格裡，而後來由 GitHub 風格 Markdown（GFM）標準化的管線符號語法，對結構相當講究。少了一行分隔列，精心排好的資料就會塌成一段亂碼，而且完全不會有錯誤訊息告訴你原因。
表格也是「原始碼長相」和「輸出結果」落差最大的元素。**粗體** 就算沒渲染，看起來也有幾分粗體的樣子。表格原始碼卻是一叢管線符號和破折號，渲染之後才會變成格子。
即時預覽的價值就在這裡。把草稿貼進編輯器，你每打一行，就能看到格子成形，或是根本成不了形。
這份資料真的適合做成表格嗎？
動手之前值得先問一句。表格對真正的表格型資料非常好用，對其他東西則相當糟糕：
- 適合 - 功能比較、選項與說明的配對、價格方案、API 參數。
- 不適合 - 儲存格要放長篇文字（改用標題加段落）、資料有層級關係（改用巢狀清單）、需要合併儲存格。
- 硬性限制 - Markdown 沒有 rowspan 也沒有 colspan，超過五、六欄在手機上就沒法看。
但只要資料合適，沒有什麼比表格說得更清楚。而且把語法真正學會只要五分鐘。我們開始吧。
基本表格語法
一個 Markdown 表格只需要三樣東西：標題列、由破折號組成的分隔列，以及一列以上的資料列。欄與欄之間用管線符號（|）隔開：
| 姓名 | 職務 | 城市 |
| ------ | ------ | ---- |
| 雅婷 | 設計師 | 台北 |
| 承翰 | 工程師 | 台南 |
| 千尋 | 文案 | 台中 |渲染結果如下：
| 姓名 | 職務 | 城市 |
|---|---|---|
| 雅婷 | 設計師 | 台北 |
| 承翰 | 工程師 | 台南 |
| 千尋 | 文案 | 台中 |
分隔列才是關鍵
分隔列就是緊貼在標題列下方的那行破折號。它負責告訴解析器「這是表格」。它不是裝飾，沒有它就沒有表格。
每一欄至少要三個破折號（---），雖然多數渲染器少幾個也認得。破折號的數量不影響欄寬，欄寬是由內容決定的。
管線符號不必上下對齊
原始碼裡的儲存格寬度完全自由。下面這段渲染出來和上表一模一樣：
| 姓名 | 職務 | 城市 |
| --- | --- | --- |
| 雅婷 | 設計師 | 台北 |把原始碼排整齊，純粹是為了方便「人」閱讀原始檔。在同事會一起維護的檔案裡值得花這個心思，在隨手回覆的留言裡就不必了。喜歡整齊但不想手動補空格的話，表格產生器會幫你把管線排好。
用冒號設定欄位對齊
欄位預設靠左對齊。在分隔列加上冒號，就能逐欄改變對齊方式：
:---- 靠左對齊（明確標示，效果同預設）:---:- 置中對齊---:- 靠右對齊
| 品項 | 數量 | 單價 |
| :------- | :--: | ---: |
| 筆記本 | 3 | $135 |
| 鋼筆 | 1 | $840 |
| 墨水匣 | 12 | $25 |渲染結果：
| 品項 | 數量 | 單價 |
|---|---|---|
| 筆記本 | 3 | $135 |
| 鋼筆 | 1 | $840 |
| 墨水匣 | 12 | $25 |
哪一欄該用哪種對齊
對齊設定作用於整欄，包含標題儲存格，沒辦法只對齊某一格。慣例其實很單純，但對表格的專業感影響很大：
- 靠右 - 數字、金額、日期。位數會對齊，眼睛順著一欄往下比較很輕鬆。
- 置中 - 簡短的狀態值：有、無、Beta、打勾符號。
- 靠左 - 其餘一律靠左，尤其是名稱和說明。
要從零開始做一張表？Markdown 表格產生器每一欄都有對齊選項，用下拉選單設定就好，不必自己數冒號。
儲存格裡可以用哪些格式
儲存格接受行內 Markdown - 凡是能放在同一行文字裡的語法都可以：
| 功能 | 狀態 | 文件 |
| ---------- | ------------- | ---------------------------- |
| **匯出** | 已完成 | [指南](https://example.com) |
| *同步* | ~~已取消~~ | `sync --help` |粗體、斜體、刪除線、行內程式碼、連結，在儲存格裡都能正常渲染。
儲存格裡放不下的東西
凡是 Markdown 視為區塊級的元素都不行：
- 換行 - 不能在儲存格裡按 Enter，因為換行代表下一列開始。解法是 HTML 標籤
<br>：寫第一行<br>第二行就會顯示成兩行。GitHub 和多數渲染器都支援，但並非所有工具都吃這招。 - 清單 - 在儲存格裡寫
- 項目，只會原封不動顯示出破折號。真的需要的話，可以用<br>硬湊（• 一<br>• 二）。 - 標題、引言、程式碼區塊 - 都是區塊級元素，一律不行。儲存格裡出現多行程式碼，就強烈暗示它該搬到表格外，用獨立的圍欄式程式碼區塊呈現。
一行原則
判斷原則很簡單。能自然放進一行的內容，儲存格就放得下；需要垂直空間的內容，就不屬於 Markdown 表格。本身有結構的內容，通常更適合寫成巢狀清單或獨立的一節。
跳脫管線符號、寬表格策略與原始碼可讀性
跳脫真正的管線符號
管線符號是欄位的分界，所以儲存格內容若含有真正的 |，就會把格子硬生生切成兩半。寫 shell 指令、正規表達式或型別聯集的文件時特別容易中招。
解法是用反斜線跳脫。寫 \|，渲染出來就是一個普通的管線符號，記錄 grep \| sort 的儲存格也就保得住欄位結構。在 GitHub 上，行內程式碼裡的反斜線跳脫同樣有效。如果某個渲染器不認帳，HTML 實體 | 是四海皆通的保險做法。
小提醒：反引號保護不了管線符號。表格解析器會先切欄位、再處理行內程式碼，所以 `a | b` 一樣會把欄位切壞。程式碼區段裡的管線也要跳脫。
馴服過寬的表格
寬表格是另一個反覆出現的頭痛來源。八個欄位、格格都是長句的表格，編輯原始碼折磨，在手機上更慘：不是滿出畫面，就是縮到看不清。硬撐之前，先試著換個形狀：
- 拆開 - 一張寬表拆成兩張窄表。
- 抽出一欄 - 把最囉嗦的那一欄改寫成表格下方的段落。
- 轉置 - 讓一堆欄變成一堆列。在 Markdown 裡，列很便宜，欄很昂貴。
粗略的判斷標準：超過五個欄位，或任何儲存格超過十來個字，資料就是在告訴你它想換一種形狀。
讓工具去打管線
只要表格夠大、夠麻煩，就別再手打管線符號。我們的表格產生器提供類似試算表的網格介面，直接輸出乾淨的 Markdown。
資料已經在別的地方了嗎？從 Excel、Google 試算表或網頁上複製，貼進表格轉 Markdown 工具，出來就是排好的管線。先寫內容，再生語法。
原始碼漂不漂亮是選擇題
管線歪七扭八的表格，渲染結果和手工精心對齊的一模一樣。檔案放在儲存庫裡、同事會直接讀原始 diff 時，值得把原始碼排整齊；一次性的留言就免了。
如果你就是喜歡整齊的原始碼，交給格式化工具或產生器去補空格。每改一個字就手動重排一次，正是人們學會痛恨表格的原因。
常見表格錯誤與修法
表格死活不渲染的時候，幾乎都是下面這五種情況之一。
五個常見兇手
- 分隔列缺失或格式錯誤。頭號元凶。標題下方那行破折號不見了、被自動修正偷換成別的字元（例如混進一個
–連接號），或和標題列之間隔了一行空行，整個區塊就會變成純文字。 - 分隔列的欄數不對。分隔列的欄數至少要和標題列一樣多。標題三欄、分隔列只有兩欄，嚴格的解析器會直接拒絕組表，GitHub 就是其中之一。數一下你的管線符號。
- 資料列的管線數量不一。儲存格太少的資料列會被補上空格子，多出來的儲存格則被默默丟掉。表格照樣渲染，但資料會跑錯欄。如果某個值看起來「往左移了一格」，回頭找找那一列前面是不是有個沒跳脫的
|。 - 表格前面沒有空行。表格緊貼在段落後面、中間沒空行時，可能整個被吸進那個段落。上下各留一行空行給它。
- 頭尾管線的疑惑。每一列開頭和結尾的管線符號在 GFM 裡是可省略的，
姓名 | 職務和| 姓名 | 職務 |效果相同。但保留它們仍是比較好的習慣：列的邊界一目了然、複製到較嚴格的工具時不易出錯，還有少數舊渲染器根本強制要求。無論選哪種，同一張表格內請保持一致。
注意：文書軟體和聊天軟體很愛把三個破折號「自動修正」成一條長橫線。如果表格是在別處寫好再貼過來的，先把分隔列重打一次，再去查其他問題。
壞掉的版本，修好的版本
把頭號兇手寫兩次給你看。前面那段會渲染成一行文字，後面那段才會變成格子：
壞掉：
| 姓名 | 職務 |
| 雅婷 | 設計師 |
修好：
| 姓名 | 職務 |
| ------ | ------ |
| 雅婷 | 設計師 |從這一組對照可以看出三件事：
- 問題出在哪 - 沒有分隔列，解析器根本沒看到表格。
- 改了什麼 - 加上一行破折號與管線，緊貼在標題列正下方，中間不留空行。
- 怎麼認出來 - 輸出裡還看得到管線符號。看得到管線，就代表表格從頭到尾沒被組起來。
一分鐘除錯任何表格
把表格貼進即時預覽編輯器，一列一列刪到它能渲染為止，再逐列加回去。加到哪一列壞掉，問題就在那一列，而且通常是一根管線符號。
如果表格在這裡渲染得出來、發佈到別處卻不行，那問題在平台，不在語法。哪些工具支援表格，語法速查表的相容性整理寫得很清楚。
相容性資料驗證日期
常見問題
Markdown 表格可以合併儲存格嗎？
不行 - Markdown 表格沒有 rowspan 或 colspan。如果資料真的需要合併儲存格，要嘛重構成多張簡單的表格，要嘛直接寫原生 HTML 的 <table>，多數 Markdown 渲染器（包括 GitHub）都會照常顯示。
怎麼在儲存格裡換行？
在想換行的位置放 HTML 標籤 <br>：第一行<br>第二行。按 Enter 沒有用，因為換行符號會結束整個表格列。注意少數嚴格的渲染器會過濾 HTML，那種情況下儲存格內就真的無法換行。
原始碼裡的管線符號需要上下對齊嗎？
不需要。原始碼對不對齊純屬外觀問題 - | a | b | 和精心補滿空格的版本渲染結果完全相同。只有在別人會閱讀原始檔時才值得對齊，而且最好交給格式化工具或產生器代勞。
為什麼我的表格渲染成純文字？
依序檢查三件事：破折號分隔列有沒有緊貼在標題列正下方（中間不能有空行）、分隔列的欄數是否不少於標題列、表格和上方段落之間有沒有空行。兇手幾乎一定是其中之一。
Markdown 表格在所有平台都能用嗎？
表格屬於延伸語法，所以不是。GitHub、GitLab、Reddit、Obsidian 和多數現代工具都支援；Discord 和一些極簡渲染器則不支援。各平台的詳細差異請見語法速查表的相容性整理。
延伸閱讀
立即使用編輯器
立即使用編輯器