Markdown 語法：所有元素一次看完

所謂「Markdown 語法」到底是什麼

Markdown 語法就是一組用標點符號標記純文字的慣例。行首放 # 代表標題，用星號包住文字代表強調，減號加空格代表清單項目。文件用純文字讀就通順，渲染器再把這些慣例轉成 HTML。

核心語法：不會壞的那一層

核心語法是 John Gruber 在 2004 年推出、後來由 CommonMark 精確定義的那一套：標題、段落、強調、清單、連結、圖片、行內程式碼、引用區塊、分隔線。只要一個工具宣稱支援 Markdown，就一定支援這些。貼到 GitHub issue、Reddit 留言、靜態網站產生器或聊天框，結果都一樣。

擴充語法：後來才加，支援不齊

擴充語法是後來各家實作各自加上去的：表格、待辦清單、刪除線、註腳、帶語言標籤的圍欄程式碼區塊，以及像 GitHub 警示區塊這類單一平台的額外功能。

「支援度廣」不等於「全部支援」。在 README 裡完美的表格，貼到聊天訊息可能變成一整排管線符號，那並不是你的語法寫錯了。

真正該問的是「它會在哪裡被渲染」

所以該問的從來不只是「這個元素怎麼寫」，還要問「負責渲染的那個東西看不看得懂」。兩件事一起看，Markdown 就不再讓人意外。下面那張表一次回答兩個問題，一個元素一列。

每個元素怎麼寫、在哪裡有效

整個語言就在這一個畫面裡。把它當成這一群頁面的地圖：每一列點名一個元素，說明它是否到處安全，並把你送到深入說明它的那一頁。

完整元素對照表

有兩列需要補充說明

• 圍欄式程式碼區塊原本屬於擴充語法，但 CommonMark 已將它納入，實務上支援度接近百分之百，可以直接當成安全的元素使用。
• 四個空格的縮排式程式碼區塊屬於核心語法，這正是為什麼清單縮排過頭時，有時會莫名其妙冒出一塊你沒要求的灰底方框。

小提醒：先看第三欄，再看第四欄。知道一個元素屬於擴充語法，等於事先知道哪些平台會讓你失望，這比把語法背起來更省時間。

如果你要的是同樣的資訊、但不要旁邊那些說明文字，Markdown 語法速查表就是為列印與常駐分頁而做的版本。

最常出問題的是哪幾個元素

幾乎每一次「我的 Markdown 壞掉了」，都能追溯到底下五個元素之一。它們都不難寫，只是渲染器對它們的看法不一致。

五個慣犯

• 表格是頭號問題，而且遙遙領先：Discord、Slack、Teams 都不支援，匯入 Notion 時也不太可靠。
• 註腳來自 PHP Markdown Extra，不屬於核心語言。GitHub 遲至 2021 年才支援，純 CommonMark 剖析器至今仍會把中括號原樣印出來。
• 待辦清單在 GitHub、GitLab、Obsidian 上會變成核取方塊，在其他地方幾乎都只是兩個中括號。
• 刪除線在多數現代工具都能用，但雙波浪號不是核心語法，較舊的剖析器會直接忽略。
• 巢狀清單壞掉的原因不是支援度，而是縮排。兩格、三格、四格空白在不同剖析器眼中意義不同，Tab 與空白混用則會讓所有剖析器一起出錯。

先確認方言，再懷疑自己打錯

真正有用的一件知識，是搞清楚你的目標平台講哪一種方言。多數現代工具已經收斂到 GitHub 風格 Markdown，也就是 CommonMark 再加上表格、待辦清單、刪除線與自動連結，本站編輯器渲染的也是這一套。

該寫哪一種 Markdown 方言說明怎麼判斷眼前是哪一種，Markdown 平台總覽則附上逐一 App 的對照表。所以東西沒有正確渲染時，先問元素是不是擴充語法，再問目的地支援到哪裡。真的很少是打錯字。

怎麼練才記得住

Markdown 是用手指學的，不是用眼睛。讀語法清單只留下「看過的印象」，實際打字才會變成「想得起來的記憶」，而你在半夜十一點趕文件時需要的是後者。

用打的，不要用看的

一個分頁開著 Markdown 編輯器，另一個開著這一頁。打一個元素，看即時預覽確認結果，再換下一個。哪個符號沒照你想的方式運作，預覽會立刻告訴你，這是最快的修正循環。

兩個值得交給工具的結構

• 管線表格。用手對齊很煩，直接在表格產生器裡做好再貼回來。
• 目錄。錨點必須跟標題完全對得上，目錄產生器可以一次生成。

注意：不要對著渲染後的畫面學語法。照抄一個標題「看起來的樣子」，學不到當初打了什麼。永遠把原始碼與預覽並排比對。

其餘的免費 Markdown 工具負責雙向轉換。語法練進手裡之後，剩下的變數就是你要發佈到哪裡，那正是 Markdown 平台總覽要處理的問題；想知道這麼小的語言為什麼會無所不在，就看什麼是 Markdown。