大於符號：引言的唯一標記
引言區塊就是開頭放一個大於符號的行。規則只有這一條：
> Markdown 的目標，是在可行範圍內
> 讓文件盡量好讀、也盡量好寫。- 行首一個
>就是引言，符號後面的空格可加可不加。 - 單獨一行
>能讓引言連貫；真正的空行則會把它切成兩段。 - 每多一個
>就多一層巢狀，實務上兩層是極限。 - GitHub 提示框與 Obsidian 標註框，本質是第一行放了
[!NOTE]這類關鍵字的普通引言。
解析器會輸出 HTML 的 <blockquote>，多數樣式表把它畫成縮排文字加上左側色條。
Markdown 本身不負責外觀，樣式全部來自周圍的 CSS。所以同一段引言在 GitHub 上是灰色面板，在部落格上可能是襯線體抽言，在郵件軟體裡只是單純縮排。解析器實際交出什麼，Markdown 與 HTML 的比較有完整說明。
符號後面的空格是必要的嗎？
不是。在 CommonMark 與 GitHub 上，>引言 與 > 引言 解析結果相同。但還是請加上空格：原始碼比較好讀，少數較舊的解析器也確實要求它。
空格多到什麼程度會出事
- 符號後面一個空格是標準寫法，到哪都安全。
- 符號後面多出四個以上空格，會變成引言內部的縮排式程式碼區塊。
- 符號前面最多三個空格會被忽略，不影響結果。
- 符號前面第四個空格會讓整行變成程式碼區塊，所以引言請貼齊左邊界。
多行引言與換行延續
多行引言的每一行都應該自己帶標記：
> 在網路上得到正確答案最快的方法，
> 不是發問，而是先貼一個錯誤答案。換行延續（lazy continuation）
Markdown 其實允許你偷懶。當引言中的段落延續到下一行時，就算那一行完全沒有標記，也會被算進同一段引言：
> 在網路上得到正確答案最快的方法，
不是發問，而是先貼一個錯誤答案。兩種寫法渲染結果一模一樣。這就是換行延續。它會存在，是因為 Markdown 當初設計給在純文字編輯器裡手動折行的人使用。它只適用於「已經在引言內」那個段落的續行。
為什麼還是該乖乖寫滿標記
只要那一行本身有能力開啟一個新區塊，換行延續就立刻失效。項目符號、標題、程式碼圍欄或表格列都會直接跳出引言，而且毫無警告：
> Pull request 請盡量小。
- 小的變更審查得比較快。第一行是引言，第二行則是落在引言外面的普通清單，原始碼完全看不出異狀。更麻煩的是，只要編輯器重新折行，斷點一移動，結果也跟著變。
小提醒：每一行都寫上 >，這一整類問題就不存在。這和清單參考裡「縮排寧可寫滿」的習慣是同一件事：寫明確，解析器就沒有猜測空間。
空行會把一段引言切成兩段
空行會終止引言區塊。看起來像「一段引言、兩個段落」的寫法，實際上是兩段各自獨立的引言：
> 引文的第一段。
> 引文的第二段。你會得到兩個相鄰的 <blockquote>，中間有明顯空隙；在 GitHub 上就是兩塊分開的灰色面板。
單獨一個標記就能讓引言連貫
把那行空行也一起引用起來，寫成後面什麼都不接的單獨 >：
> 引文的第一段。
>
> 同一段引文的第二段。就是這一個字元，決定你得到的是一段引言還是兩段，也回答了大部分「引言中間為什麼有空隙」的疑問。
同一個標記也用來區隔其他區塊
在引言內部，單獨的 > 扮演的是一般 Markdown 中空行的角色。以下情況都要用它：
- 同一段引文的兩個段落之間
- 標題與它底下的段落之間
- 段落與接在後面的清單之間
- 段落與程式碼圍欄的開頭之間
巢狀引言與郵件式回覆
每多一層就多一個標記。兩個標記就是引言裡的引言：
> > 這個端點是不是該改成非同步？
>
> 該改，而且還要加上逾時設定。標記之間的空格可有可無，因此 >> 與 > > 意思相同。每一層都會再包一層 <blockquote>，而多數佈景主題每層都會縮排。三、四層之後文字只剩窄窄一條，兩層就是實務極限。
郵件式回覆
巢狀引言最有價值的場合就是討論串。郵件論壇與純文字電子郵件用 > 標示引用內容，遠早於 Markdown 出現，Markdown 也原封不動繼承了這個慣例。最舊的訊息縮在最裡層：
> > > 我們禮拜五能上線嗎？
> >
> > 要看資料庫遷移有沒有審查完。
>
> 今天早上已經審完了。
那就出貨吧。巢狀引言最容易塌陷的地方
這種寫法一定要每行補滿標記。跨層級的換行延續正是回覆鏈崩掉的元凶：標記比上一行少的那一行，會被吸進較深的段落，而不是像大家預期的那樣另起一層較淺的引言。
引言裡可以放哪些元素
引言區塊可以容納任何區塊內容：段落、標題、清單、程式碼圍欄、表格、圖片，甚至其他引言。規則只有兩條。
- 那些內容的每一行都要有
>標記，看起來空空如也的行也一樣。 - 區塊之間用單獨的
>分隔，不能用真正的空行。
> ### 發佈檢查清單
>
> 1. 打上版本標籤
> 2. 發佈更新說明
>
> ```bash
> git tag -s v2.1.0
> ```
>
> 兩道圍欄都要有標記，不是只有中間的程式碼。引言內的縮排是去掉標記之後才算的，所以巢狀清單的行為跟引言外面完全一樣。空格數見清單參考，圍欄規則見程式碼區塊參考。
各種區塊的寫法與注意事項
| 元素 | 在引言裡的寫法 | 要注意的地方 |
|---|---|---|
| 段落 | > 一段文字 | 沒有特別限制 |
| 第二個段落 | 中間放單獨的 > | 真正的空行會終止引言 |
| 標題 | > ## 標題 | 在 GitHub 上仍會進入頁面大綱 |
| 符號清單 | > - 項目 | 每一個項目都要有標記 |
| 編號清單 | > 1. 項目 | 續行也一樣要補 |
| 巢狀清單 | > - 子項目 | 縮排從 > 之後開始算 |
| 圍欄式程式碼 | > ``` 單獨一行 | 開頭與結尾圍欄都要有 |
| 縮排式程式碼 | > 加四個空格 | 很容易不小心觸發 |
| 表格 | > | A | B | | 表頭、分隔列與每一列都要 |
| 圖片 | >  | 寬度受引言限制，不是整頁寬 |
| 連結 | > [文字](/page) | 沒有特別限制 |
| 分隔線 | > --- | 緊接在文字下方會變成標題 |
| 巢狀引言 | > > 被引用的回覆 | 標記之間的空格可省略 |
| 待辦清單 | > - [ ] 項目 | 限 GFM，而且一律不可點選 |
注意：表格放進引言後，寬度是引言的寬度而不是整頁寬，欄位很快就會擠在一起。什麼時候該把表格拉出來獨立成一節，表格參考有說明。
出處與署名怎麼寫
Markdown 沒有署名語法，所以以下每一種寫法都只是社群慣例，不是規範。最常見的做法是在引言最後一行放一個破折號加上名字：
> 簡潔是複雜的極致。
>
> - 達文西印刷上這個符號通常排成長破折號，但在原始檔裡用普通連字號才安全：跨編輯器複製貼上不會走樣，存成錯誤編碼時也不會變成亂碼。
名字為什麼會變成項目符號
連字號後面接空格就是清單語法，所以上面的範例會把名字渲染成一個項目符號。有些佈景主題看起來像刻意設計，有些則像出了錯。
三種保持純文字的做法
- 把連字號跳脫掉，破折號留著，項目符號消失。
- 把名字改成斜體，讀起來像附註而不是清單項目。
- 改用巢狀引言，把出處和引文本身區隔開來。
> 簡潔是複雜的極致。
>
> \- 達文西
>
> *達文西，傳為其言*巢狀引言的版本，讀起來像是針對這段引文的附註，而不是引文的一部分：
> 簡潔是複雜的極致。
>
> > 達文西，普遍認為出自其口允許行內 HTML 的地方可以直接用 <cite> 取得語意；不允許的地方，用粗體與斜體參考裡的斜體寫法就很夠用。
GitHub 提示框與 Obsidian 標註框
GitHub 在 2023 年底推出提示框（alerts），直接建立在引言語法之上。引言的第一行是一個加了驚嘆號的方括號關鍵字，內文接在下一行：
> [!NOTE]
> 讀者不該跳過的重要資訊。
> [!WARNING]
> 忽略之後可能出事的注意事項。GitHub 檢查的三條規則
- 關鍵字必須全大寫：
[!NOTE]可以，[!note]不行。 - 它必須自成一行，而且是引言的第一行，內文寫在下一行。
- 一段引言只能放一個提示框，也不支援巢狀提示框。
三條都對，GitHub 就會畫出帶色邊框、圖示與粗體標籤；錯一條，你得到的是一段方括號原樣顯示的普通引言。方言的其他部分請見 GFM 參考。
在其他渲染器上會怎樣
提示框是優雅降級，不是直接壞掉。沒聽過這套語法的渲染器只會看到一段普通引言，第一行剛好是 [!NOTE] 這串文字，內容照樣可讀。這個划算的取捨，正是它建立在引言語法上的原因。
Obsidian 標註框多做了什麼
Obsidian 標註框沿用同一套基礎語法，另外多了四件事：
- 關鍵字清單長得多，連
[!BUG]、[!EXAMPLE]都有 - 接受小寫，所以
[!tip]也能生效 - 可以在同一行加上自訂標題
- 用結尾的
+或-控制展開與收合
> [!tip] 比你想的還好用
> 標註框的標題是選填的。
> [!warning]- 預設收合
> 減號會讓這一塊載入時就是收起來的。所有關鍵字與支援平台
| 語法 | 渲染結果 | 支援平台 |
|---|---|---|
> [!NOTE] | 藍色提示框，標示為 Note | GitHub、GitLab、Obsidian |
> [!TIP] | 綠色提示框，選擇性建議 | GitHub、GitLab、Obsidian |
> [!IMPORTANT] | 紫色提示框，務必閱讀 | GitHub、GitLab、Obsidian |
> [!WARNING] | 琥珀色提示框，有風險的步驟 | GitHub、GitLab、Obsidian |
> [!CAUTION] | 紅色提示框，可能造成損害 | GitHub、GitLab、Obsidian |
> [!INFO] | 中性資訊標註框 | 僅 Obsidian |
> [!SUCCESS] | 綠色打勾標註框 | 僅 Obsidian |
> [!QUESTION] | 問號標註框 | 僅 Obsidian |
> [!FAILURE] | 紅色叉號標註框 | 僅 Obsidian |
> [!BUG] | 臭蟲圖示標註框 | 僅 Obsidian |
> [!EXAMPLE] | 清單圖示標註框 | 僅 Obsidian |
> [!QUOTE] | 引號圖示標註框 | 僅 Obsidian |
> [!NOTE]- 標題 | 載入時收合的標註框 | 僅 Obsidian |
| 任何無法辨識的關鍵字 | 普通引言，方括號原樣顯示 | 其餘所有渲染器 |
小提醒：關鍵字要照「對讀者的風險」來挑，不是照你喜歡的顏色挑。[!WARNING] 留給可能弄壞東西的步驟，[!NOTE] 給背景說明，[!TIP] 給可以略過的建議。連續四個提示框，只會訓練讀者四個都跳過。
常見錯誤與修正寫法
幾乎所有壞掉的引言都逃不出這五種錯誤，而且每一種都只要改一行：
- 引言前面沒有空行，標記被上一個段落吞掉。
- 該放單獨
>的地方放了空行，一段引言被切成兩段。 - 清單或圍欄漏掉標記，後面整個區塊跟著跑出引言。
- 提示框關鍵字寫成小寫，或跟內文擠在同一行。
- 引言行尾有多餘空白，強制斷行，段落變成參差不齊的短行。
修正兩種空行錯誤
CommonMark 與 GitHub 允許引言直接插斷段落，但 MkDocs 使用的 Python-Markdown 不行，原始的 Markdown.pl 與許多 wiki 也不行，它們只會印出一個字面上的 >。錯誤寫法與正確寫法：
寫作規範是這樣說的：
> 句子請盡量短。寫作規範是這樣說的：
> 句子請盡量短。第二種錯誤剛好相反：引言內部放了真正的空行，於是變成兩段中間有空隙的引言。錯誤寫法與正確寫法：
> 第一段。
> 第二段。> 第一段。
>
> 第二段。修正漏掉的標記
沒有標記的那一行會跳出引言，後面的內容也一起跑出去。錯誤寫法與正確寫法：
> 檢查清單：
> - 打上版本標籤
- 發佈更新說明> 檢查清單：
>
> - 打上版本標籤
> - 發佈更新說明修正渲染成普通引言的提示框
GitHub 只認「自成一行的全大寫關鍵字」。下面兩種寫法都會失敗，而且都會留下裸露的方括號：
> [!note] 記得輪替簽章金鑰
> [!NOTE] 記得輪替簽章金鑰> [!NOTE]
> 簽章金鑰每 90 天要輪替一次。其他狀況怎麼除錯
流程和 Markdown 其他元素一樣：把引言貼進編輯器，一行一行刪到它正確渲染為止。最後刪掉的那一行就是元凶，原因幾乎都是漏掉標記或空行放錯位置。
空行在這個格式裡承載了大量意義，原因請見 Markdown 的設計初衷。語法速查表把引言寫法濃縮在一頁，完整指南把引言擺回其他元素之間，標題與註腳則涵蓋最常和引文搭配的兩種元素。
相容性資料驗證日期
常見問題
Markdown 引言區塊的 > 後面一定要空格嗎？
在 CommonMark 與 GitHub 上不必，>引言 和 > 引言 解析結果相同。但為了可讀性與少數較舊的解析器，還是建議加上。要避免的是符號後面多出四個以上空格，那會被當成引言內部的縮排式程式碼區塊。
一段引言裡要放兩個段落該怎麼寫？
在兩段之間放一行單獨的 >。真正的空行會終止引言，於是你會得到兩段中間有空隙的獨立引言。同一個單獨標記也用來把標題、清單或程式碼圍欄和上一個段落隔開。
巢狀引言（引言裡的引言）怎麼寫？
每一層放一個標記：> > 內層引言，標記之間的空格可省略。請每一行都明確寫滿標記，因為標記數量比上一行少的行，通常會被吸進較深的引言，而不是另起一層較淺的引言。
GitHub 的 [!NOTE] 提示框在其他平台能用嗎？
在 GitHub、GitLab 與 Obsidian 上會渲染成帶色的提示框。其他平台則降級成普通引言，第一行顯示字面上的 [!NOTE]，不會壞掉，內容照樣可讀。Obsidian 支援的關鍵字多得多，而且接受小寫。
為什麼我的署名那一行變成項目符號了？
因為連字號加空格就是清單語法。解法有三種：用反斜線跳脫連字號、把名字改成斜體，或把署名放進巢狀引言。三種都能避開清單，原始檔也都還是好讀。
延伸閱讀
立即使用編輯器
立即使用編輯器