Markdown 語法從標題到表格，連全形標點讓粗體失效也講清楚

一段只有井字號、星號和直線的文字，放進 GitHub 會變成排好版的標題、粗體和表格，貼進記事本卻原樣露出每一個符號。文字本身沒有任何變化，差別在於有沒有一個程式把這些符號讀懂，而這套約定好的寫法，就是 Markdown。

Markdown 的符號不難記，真正容易出錯的是細節，像是標題的井字號後面少一個空格就不生效，粗體的星號內側緊貼全形引號，星號就會原樣露出，巢狀清單少縮排一格就變成兩份清單。再加上不同平台各自加了延伸功能，同樣的 Markdown語法 在 A 平台正常、在 B 平台走樣，並不奇怪。

要判斷一個符號為什麼生效或失效，得先分清楚原始碼和呈現結果其實是兩份獨立的東西。

Markdown 是什麼？

Markdown 是一種用純文字寫出排版意圖的格式。John Gruber 在 2004 年發表它，Aaron Swartz 在語法設計上提供了重要的回饋。Gruber 同時附上一支用 Perl 寫成的轉換工具 Markdown.pl，負責把純文字的標記轉成 HTML。所以 Markdown 其實有兩層意思，一層是寫作時使用的符號約定，也就是一般說的 Markdown語法，另一層是把這些符號轉成網頁的工具。

Gruber 在專案頁寫明，Markdown 語法最重要的設計目標是盡可能好讀，最大的靈感來源則是純文字電子郵件的格式。這個目標帶來一個很實用的結果，原始碼在轉換之前，本身就讀得懂。例如下面這一小段，即使沒有任何程式幫忙轉換，也看得出哪裡是標題、哪裡是清單。

## 龐果設計的配色規範

主色用**深藍色**，輔色有兩種：

- 淺灰色
- 米白色

完整色票請看[色票頁](https://example.com/colors)。Code language: Markdown (markdown)

經過轉換，第一行變成大字的標題，「深藍色」變成粗體，兩個顏色變成帶圓點的清單，最後的「色票頁」則變成可以點擊的連結。這種檔案通常存成 .md 副檔名，內容仍是純文字，任何文字編輯器都打得開，只有支援 Markdown 的應用程式才會把符號轉成排版。

而同一份原始碼交給不同的轉換程式，呈現結果也不一定相同。

CommonMark、GFM 與各平台方言的關係

Gruber 的原始描述有個先天的限制，它沒有把語法定義到毫無歧義。CommonMark 規格的前言就明說，Gruber 的描述並沒有明確規定語法，並舉出一些沒有答案的問題，像是清單標記從數字換成符號時算一份清單還是兩份，以及強調符號的優先順序該怎麼排。當 Markdown 後來出現數十種實作，同一份原始碼在不同地方被各自解讀，也就成了常態。

CommonMark 就是為了補上這個缺口而寫的規格，它把每個語法寫成無歧義的規則，並附上大量範例，現行版本是 2024 年 1 月 28 日的 0.31.2。在這之上，GitHub 又加了一層。依 GFM 規格的自述，GFM 是 GitHub.com 與 GitHub Enterprise 上使用者內容所支援的 Markdown 方言，同時是 CommonMark 的嚴格超集。CommonMark 沒有、而 GitHub 支援的功能，規格稱為延伸，包含表格、待辦清單、刪除線與自動連結。

整理成表格，這幾層的分工大致如下。

原設計文件列出的元素稱為基礎語法，延伸語法則是表格、程式碼區塊的語法上色、註腳這類不是每個工具都有的功能，使用之前要先查該工具的說明。這也是 Markdown語法 在不同平台上表現不一的主要原因。

後面的內容，除了特別標明延伸的部分，都以 CommonMark 為準。遇到不確定的語法，最快的辦法是貼進該平台的預覽區看一次。

標題的 6 個層級與井字號後的空格

標題是 Markdown 最常用，也最常寫壞的語法。寫法是在行首放井字號，井字號的數量就是層級，1 個是第一層標題，6 個是第六層標題，對應 HTML 的 H1 到 H6，7 個以上則不算標題，只會當成一般段落。

# 龐果設計品牌手冊
## 配色規範
### 主色
#### 深藍色
##### 使用場合
###### 注意事項Code language: Markdown (markdown)

井字號後面一定要留一個空格，或是直接換行。少了空格的 #標題，在 CommonMark 相容的解析器裡只是一般段落，井字號會原樣露出來。不同工具對缺空格的處理並不一致，一律留空格最保險；標題前後各空一行，相容性也最好。

#配色規範
# 配色規範Code language: Markdown (markdown)

這兩行裡，只有第二行會變成標題，第一行會原樣顯示成「#配色規範」。

標題還有一種舊式寫法，在文字的下一行放等號或減號，等號代表第一層標題，減號代表第二層標題。

配色規範
========

主色
----Code language: Markdown (markdown)

這種寫法留下了一個陷阱。一行文字緊接著下一行的 ---，會被當成第二層標題，而不是分隔線。想畫分隔線，文字和 --- 之間要隔一個空行。

這是一行文字
---

這是另一行文字

---Code language: Markdown (markdown)

前一組會變成第二層標題，後一組才是一段文字加一條分隔線。

另外，GitHub 的說明提到，檔案裡有兩個以上的標題時，檔案頂端會出現「Outline」選單，可以開啟自動產生的目錄。標題層級寫得清楚，長文件在 GitHub 上找段落也比較方便。

段落靠空行分隔，強制換行有 3 種寫法

新手最常困惑的是，明明按了 Enter，顯示出來卻還是連在一起。Markdown 的段落靠空行分隔，一段文字裡單純換行，轉換之後會被併成同一段。

第一行文字
第二行文字

這是新的一段Code language: Markdown (markdown)

前兩行會併成同一段，空一行之後才是新的段落。段落的第一行也不要用空格或 tab 縮排，前面多出 4 個空格，整段就會被當成程式碼區塊。

要在同一段裡強制換行，有三種寫法。

1. 行尾放 2 個以上的空格
2. 行尾放一個反斜線
3. 行尾放 HTML 的 <br> 標籤

第一行文字\
第二行文字<br>第三行文字Code language: Markdown (markdown)

這三種寫法各有取捨。行尾 2 個空格幾乎所有工具都認得，缺點是在原始碼裡看不見，容易誤加，也容易被編輯器自動刪掉；反斜線寫法則不是每個工具都支援；<br> 要看該平台允不允許 HTML。所以換平台之前，先用預覽確認換行有沒有出現。

GitHub 還有一個容易被忽略的差異。根據它的說明文件，在 issue、PR 和討論區裡，單純按 Enter 就會顯示成換行，但同樣的寫法放進 .md 檔，換行就不會出現，要用上面三種寫法之一才行。兩行之間若空一行，兩處都會分成兩段。同一段文字在兩個地方顯示不同，原因是兩邊套用的換行規則本來就不一樣。

粗體、斜體與刪除線的符號寫法

強調符號可以用星號，也可以用底線，兩者能互換，同一份文件選一種統一使用即可，基本寫法如下。

這是 *斜體*，也可以寫成 _斜體_
這是 **粗體**，也可以寫成 __粗體__
這是 ***粗斜體***
這是 ~~刪除線~~Code language: Markdown (markdown)

斜體用單個星號或底線包住，粗體用兩個，三個則是同時粗體加斜體；粗體裡面還可以再巢狀斜體，寫成 **文字 _強調_ 文字**。刪除線不屬於 CommonMark，是 GFM 的延伸，寫法是用兩個波浪號包住，GitHub 也接受單個波浪號。

標準 Markdown 沒有底線，也沒有上標與下標。需要這些效果時，要改用 HTML 的 <ins>、<sup>、<sub> 標籤，GitHub 都支援，實際寫法在後面講 HTML 的段落有範例。

夾在單字中間的底線不會產生強調

同一個強調，用星號和用底線，在字中間的結果並不同。CommonMark 規格自己就用這組例子說明，星號可以強調字中間的一部分，底線則不行。

foo*bar*baz
foo_bar_bazCode language: Markdown (markdown)

第一行的 bar 會變成斜體，第二行則原樣顯示，底線不會產生強調。

這其實是設計原意。英文變數名常常含有底線，例如 snake_case_name，如果底線能在字中間強調，這類名稱就會被誤判成斜體。中文夾在文字中間的底線強調，同樣不會生效，中文_底線_中文 不會變成斜體。要強調字中間的一部分，一律改用星號。

全形標點緊貼星號內側時強調會失效

中文使用者最需要留意的一個陷阱，是強調符號緊貼全形標點。下面三行，在 CommonMark 相容的解析器裡，星號都不會被當成粗體，會原樣顯示出來。

他說**「重點」**後面還有字
**注意：**請先備份
請參考**《設計原則》**一書Code language: Markdown (markdown)

原因在於規則會看符號前後的字元類型。一個 ** 如果朝向粗體內容的那一側貼著標點、外側又緊貼著文字，就不會被視為可以起頭或收尾的符號。這三行的 ** 都落在這種位置，例如第二行的收尾 ** 前面是全形冒號、後面是「請」字，所以粗體沒有關閉。反過來，標點在星號外側時不受影響，像 他說**重點**。 或 「**重點**」 都能正常顯示成粗體。

有兩種改法。一種是把標點移到星號外面，另一種是在星號的外側留一個空格。

**注意**：請先備份
**注意：** 請先備份
他說 **「重點」** 後面還有字Code language: Markdown (markdown)

這三行在 CommonMark 相容的解析器裡都能正常顯示成粗體。各平台對中日韓文字的處理不一定相同，上面這些寫法在其他平台的結果可能不一樣，仍以實際的預覽為準。

無序、有序清單的標記與巢狀縮排

清單標記要一致，有序清單只看第一個數字

無序清單可以用 -、*、+ 任一個當標記，有序清單則是數字加句點。同一份清單內，標記要保持一致。

- 名片
- 型錄
- 海報

1. 開啟檔案
2. 選擇尺寸
3. 匯出 PDFCode language: Markdown (markdown)

有序清單只認第一個數字，它決定清單從哪個數字開始，後面的數字大小不影響順序。下面這份清單會從 3 開始，依序顯示成 3、4、5。一般仍建議從 1 開始，比較不容易出錯。

3. 第三步
1. 第四步
7. 第五步Code language: Markdown (markdown)

中途換標記，會斷成兩份清單。數字清單後面接符號，或是無序清單從 - 換成 *，解析器都會當成新的一份。清單項目之間若空一行，則會變成「疏鬆清單」，只要其中任何兩項之間有空行，整份清單的每一項都會包成段落，間距也跟著拉開。

另外還有兩個相容性的小細節。有序清單的標記，1) 這種括號寫法只有 CommonMark 等少數工具支援，用句點最通用。清單的前面最好空一行，相容性也比較好。

巢狀清單的子項要縮排到上一項文字的起點

子項要縮排到上一項文字開始的位置，這是巢狀清單唯一要記的原則。- 這個標記佔 2 個字元，文字從第 3 欄開始，所以子項縮排 2 個空格；1. 佔 3 個字元，文字從第 4 欄開始，子項就要縮排 3 個空格。

- 印刷檔案
  - 出血
  - 色彩模式Code language: Markdown (markdown)

1. 準備檔案
   - 確認尺寸
   - 轉成 PDFCode language: Markdown (markdown)

縮排不夠時，子項就不會巢狀。有序項只縮 2 個空格，後面的子項會變成獨立的一份無序清單；無序項只縮 1 個空格，子項則變成與它同一層的項目。

1. 準備檔案
  - 確認尺寸Code language: Markdown (markdown)

- 印刷檔案
 - 出血Code language: Markdown (markdown)

數字的位數越多，標記就越長，縮排也要跟著增加。GitHub 的說明舉了一個例子，100. First list item 的標記佔 5 個字元，所以底下的子項至少要縮排 5 個空格。

在 GitHub 的網頁編輯器裡，選取多行文字後按 Tab 可以增加縮排，按 Shift+Tab 則減少縮排，比手動數空格可靠。

連結與圖片共用一組括號結構

連結與圖片的寫法幾乎一樣，圖片只在最前面多一個驚嘆號。兩者的差別在方括號裡的文字，連結的是可以點擊的文字，圖片的則是替代文字。

行內連結、參考式連結與自動連結

行內連結是方括號放顯示的文字，圓括號放網址，網址後面還可以用引號附上選填的標題。GitHub 的說明要求連結文字寫在同一行，跨行寫的連結文字不會生效。

[龐果設計的配色規範](https://example.com/colors "配色規範")Code language: Markdown (markdown)

網址裡如果有空格，可以把整個網址放進角括號，或是把空格改寫成 %20。

參考式連結把顯示的文字和網址拆開寫。正文只放 [文字][代號]，網址則用 [代號]: 網址 另外定義，定義可以放在文件的任何位置，使用它的連結之前或之後都行。這種寫法適合同一個網址要反覆使用，或是想讓正文讀起來乾淨的時候。

先看[配色規範][colors]，再看[字體規範][fonts]。

[colors]: https://example.com/colors "配色規範"
[fonts]: https://example.com/fontsCode language: Markdown (markdown)

那兩行定義不會出現在畫面上，它們只負責把代號對應到網址。

最後是直接貼網址的情況。GFM 會把有效的網址自動轉成連結，CommonMark 則要用角括號包起來才算，也就是 <https://example.com>。

圖片的替代文字、相對路徑與尺寸限制

圖片的寫法是驚嘆號、方括號加圓括號。方括號裡的文字會變成 HTML 的 alt 屬性，也就是替代文字。圖片載入失敗時，畫面上會顯示這段文字，螢幕閱讀器也會把它唸出來，所以要寫圖片傳達的資訊，而不只是檔名。

![龐果設計的 Logo，藍底白字](images/logo.png)Code language: Markdown (markdown)

圖片的路徑如果指向同一個專案裡的檔案，用相對路徑會比貼完整網址穩定。GitHub 會依目前的分支自動調整相對路徑；路徑是相對於目前的檔案，以 / 開頭則是相對於專案根目錄。

另一個限制是，Markdown 本身沒有指定圖片尺寸的語法。要控制大小，得改寫成 HTML 的 <img> 標籤，而且該平台要允許 HTML 才行。

<img src="images/logo.png" alt="龐果設計的 Logo，藍底白字" width="200">Code language: Markdown (markdown)

GitHub 依標題文字自動產生錨點

想從頁面的某處連到同一頁的另一個標題，得先知道標題會自動產生什麼名稱的錨點。以下以 GitHub 的規則為例，其他平台的規則可能不同。

1. 英文字母轉成小寫
2. 空格換成連字號，其他空白與標點移除
3. 前後多餘的空白去掉
4. 標題裡的標記格式移除，只保留文字

GitHub 的說明用下面這個標題舉例。撇號與驚嘆號被移除，斜體的底線被移除，希臘字母 Θ 這種非 ASCII 字元則保留下來。

## This'll be a _Helpful_ Section About the Greek Letter Θ!

[連結](#thisll-be-a-helpful-section-about-the-greek-letter-Θ)Code language: Markdown (markdown)

中文標題也是同樣的道理，非 ASCII 字元會保留，所以「配色規範」這個標題的錨點就是 #配色規範。這個規則只代表 GitHub，其他平台怎麼處理中文標題，要看該平台的說明。

同一頁出現相同標題時，第二個起會在錨點後面加上 -1、-2。因為錨點由標題文字決定，改了標題或調整了相同標題的順序，原本的連結就會失效，要同步更新。

引用區塊與分隔線的寫法

引用區塊以大於符號開頭。引用有多段時，段落之間的空行也要加上大於符號，否則兩段會變成各自獨立的引用；要巢狀引用，就連寫兩個大於符號。

> 第一段引用。
>
> 第二段引用。
>> 巢狀引用Code language: Markdown (markdown)

引用裡面也可以放標題、清單、強調等其他語法，不過不是所有元素都能放，用之前先預覽確認。引用前後各空一行，相容性也比較好。GitHub 會把引用顯示成左側一條直線，加上灰色的字。

分隔線是單獨一行的 3 個以上 -、* 或 _，前後各空一行。

---
***
___Code language: Markdown (markdown)

這三種寫法都會畫出同樣的分隔線。前面講過，--- 如果緊貼在文字的下一行，會被當成標題，所以它的上一行一定要是空行。

行內程式碼用反引號，整塊程式碼用圍籬包住

行內程式碼用單個反引號包住，裡面的內容不會再套用任何格式。

輸入 `git status` 查看目前狀態。Code language: Markdown (markdown)

如果程式碼本身含有反引號，外層就改用兩個反引號。

`` 這裡面可以有 ` 單個反引號 ``Code language: Markdown (markdown)

整塊的程式碼用圍籬標出，圍籬由 3 個以上連續的反引號或波浪號組成，兩者不可混用。開頭那一行的圍籬後面可以接語言名稱，像 python、markdown，讓平台依語言上色；結束的圍籬必須是同一種符號，而且至少跟開頭一樣長。

圍籬的長度規則有一個直接的用途。如果範例裡本身就含有 3 個反引號的區塊，外層沿用 3 個，內層的第一組 3 個反引號就會被當成結束圍籬，範例在中途斷掉。解法是外層改用 4 個反引號，內層維持 3 個。

```python
print("龐果設計")
```Code language: Markdown (markdown)

像上面這個範例，如果要把它放進一份 Markdown 文件原樣顯示，外層就得是 4 個反引號。外層也可以改用波浪號，同樣能把反引號圍籬包在裡面。

~~~markdown
```python
print("龐果設計")
```
~~~Code language: Markdown (markdown)

舊式的寫法是把每一行縮排 4 個以上的空格。這種縮排式程式碼區塊不能指定語言，前面要有空行，也不能打斷前一個段落，現代寫法大多改用圍籬。GitHub 另外有個特例，在 issue、PR 和討論區裡，用反引號包住色碼，例如 #0A58CA，會在旁邊顯示成色塊，這個特例僅限這些地方。

用反斜線跳脫符號，標準語法做不到的改用 HTML

寫作時有時只想把 Markdown 的符號當一般的字顯示，這時在符號前面加一個反斜線，就能讓它失去格式的作用。

把 \*龐果設計\* 這個詞原樣顯示，不要變成斜體。Code language: Markdown (markdown)

星號前面有反斜線，所以兩個星號都會原樣顯示出來。反斜線跳脫只對 Markdown 的符號有效，在程式碼區塊、行內程式碼、自動連結和原始 HTML 內不生效，這也代表程式碼裡不必另外加反斜線。在連結網址、連結標題、圍籬的語言名稱這類位置，跳脫則照常有效。

Markdown 的另一個補救辦法，是直接寫 HTML。很多平台允許在 Markdown 裡嵌入 HTML，用來補標準語法沒有的效果。GitHub 的說明列出幾個例子，<sub> 做下標，<sup> 做上標，<ins> 做底線，另外還支援 <picture>；用 <!-- --> 包住的 HTML 註解則不會顯示在畫面上。

H<sub>2</sub>O 與 x<sup>2</sup>，還有 <ins>底線文字</ins>。

<!-- 這一行是註解，不會顯示 -->Code language: Markdown (markdown)

不過不是每個平台都允許 HTML，有的會過濾掉部分標籤，有的完全不允許。前面介紹的 <br> 與 <img> 也一樣，使用之前要先查該工具的說明。

表格、待辦清單、註腳與提示區塊等延伸語法

表格、待辦清單、註腳與提示區塊跟前面的語法不同，都是延伸語法，不是每個平台都支援。其中表格和待辦清單是 GFM 規格列出的延伸，註腳與提示區塊則是 GitHub 平台提供的功能，使用之前要先確認目標平台認不認得。

表格的分隔列、對齊冒號與欄數規則

表格用直線和橫線組成，第一列是表頭，第二列是分隔列，每一欄由連字號組成，GitHub 的說明要求每一欄至少三個，之後才是資料列。

| 用途 | 字體 | 字級 |
| :--- | :---: | ---: |
| 標題 | 黑體 | 24 |
| 內文 | 宋體 | 14 |Code language: Markdown (markdown)

分隔列裡的冒號決定對齊方式，冒號在連字號左邊是靠左，兩側都有是置中，在右邊是靠右。兩端的直線可以省略，欄寬也不必對齊，儲存格裡可以放行內程式碼、連結與強調。儲存格內要顯示直線本身，得寫成 \|。

表格最容易出錯的地方，是欄數對不上。表頭列和分隔列的欄數必須一致，否則整張表都不會被辨識成表格；資料列的欄數如果不夠，GFM 會補上空儲存格，超出的部分則被忽略。表格會在第一個空行，或是另一種區塊開始的地方結束。GitHub 另外要求表格前面必須有空行才能正確顯示，所以表格前先空一行是個好習慣。

待辦清單的核取方塊寫法

待辦清單是清單的延伸，在項目前面加上方括號，空白代表未完成，x 代表已完成。

- [ ] 確認配色規範
- [x] 匯出 Logo 檔案Code language: Markdown (markdown)

轉換之後，這兩行會變成核取方塊。方括號裡只能是一個空白或 x，大寫 X 也可以。這是 GFM 的延伸，CommonMark 本身沒有，不支援的解析器會把它當成一般清單，方括號原樣顯示。

如果項目的文字以圓括號開頭，GitHub 的說明要求先用反斜線跳脫，否則不會正確顯示。

- [ ] \(選填) 補上英文版Code language: Markdown (markdown)

註腳與 GitHub 提示區塊

註腳與提示區塊都是看起來像標準語法、實際上屬於平台延伸的功能。註腳的寫法是內文標 [^1]，說明另外寫在 [^1]: 後面。

Markdown 由 John Gruber 發表[^1]。

[^1]: 2004 年。Code language: Markdown (markdown)

不論定義寫在文件的哪個位置，註腳都會顯示在頁面的最底部。GitHub 的 wiki 不支援註腳。

提示區塊是以引用語法為基礎的延伸，引用的第一行放 [!NOTE] 這類標記，內容寫在後面。GitHub 有 NOTE、TIP、IMPORTANT、WARNING、CAUTION 五種類型。

> [!NOTE]
> 這是一則提示。Code language: Markdown (markdown)

GitHub 建議提示區塊只在內容對使用者能否成功很關鍵時才用，每篇文章限一兩個，並避免連續放置；提示區塊也不能巢狀在其他元素裡。貼到只支援標準語法的地方，這個區塊只會顯示成一般引用，第一行還會原樣露出 [!NOTE]。使用這兩項功能之前，先查目標平台的說明比較穩妥。

語法沒有生效時，依畫面現象回推原因

語法沒有寫錯卻不生效，原因多半在環境，不在符號本身。依畫面上看到的現象往回找，通常比逐個符號檢查來得快。

排查時最有效的做法，是把同一份原始碼貼進另一個預覽環境對照。如果兩邊的結果不同，問題就出在方言，而不在寫法。

AI 助手回覆的符號，貼進 Google 文件的轉換方式

許多人第一次接觸 Markdown，是在 AI 助手的回覆裡。回覆中的 ### 就是第三層標題，被雙星號包住的文字是粗體，一排 |---|---| 則是表格的分隔列。這些符號貼進支援 Markdown 的地方會轉成排版，貼進不支援的地方就原樣露出來，看起來像一堆符號。

Google 文件有支援這類轉換。先在「Tools > Preferences」勾選「Enable Markdown」，之後在文件裡按右鍵選「Paste from Markdown」，貼上的 Markdown 就會轉成文件格式。反過來，選取內容後按右鍵選「Copy as Markdown」，可以複製成 Markdown 的文字；「File > Download > Markdown (.md)」可以匯出整份文件，「File > Open > Upload」則可以匯入 .md 檔。這些選項在中文介面裡會以對應的中文翻譯顯示，名稱以 Google 說明所列的英文為準。

Google 的說明也列出支援的語法，包括標題、斜體、粗體、刪除線與連結。其中標題的井字號後面同樣要有空格，刪除線用的是單個波浪號，這也是前面提到 GitHub 同樣接受的寫法。

寫提示詞時，Markdown 也派得上用場。OpenAI 的提示工程文件指出，Markdown 的標題與清單可以用來標示提示詞的不同區段，並向模型傳達層級。

Markdown 的符號雖然不多，真正要練的是判斷，也就是符號旁邊緊貼著什麼字元、縮排對齊在哪個位置、這個平台支援到哪一層。往後在新的平台寫第一份 markdown 時，先寫一小段貼上預覽，確認標題、清單和粗體都正常，再繼續寫下去。