Markdown 分割線（水平線）語法教學

寫長文件的時候，在兩個主題之間插一條分割線（horizontal rule），能讓內容結構更清晰。Markdown 的分割線語法特別簡單——三個字元就能搞定，但有幾個小坑值得注意。

Markdown 分割線的基本語法

在 Markdown 裡，分割線有三種寫法，效果完全一樣：

---

***

___

三種寫法渲染出來的結果都是一條橫貫頁面寬度的水平線，對應的 HTML 標籤是 <hr>。

根據 CommonMark 規範，這三種寫法也叫「主題分隔」（thematic break）。你用哪種都行，關鍵是至少要寫三個字元，而且必須單獨佔一行。

超過三個也行，比如 ----- 或 *******，效果不變。

三個短橫線（最常用）

第一部分內容。

---

第二部分內容。

這是最多人用的寫法。GitHub 上大約 92% 的 Markdown 檔案都用 --- 來做分割線。

三個星號

第一部分內容。

***

第二部分內容。

星號寫法有個好處：不會和標題語法衝突（後面會詳細說）。如果你特別在意這一點，可以用星號代替短橫線。星號之間加空格也行，* * * 是合法寫法。

三個底線

第一部分內容。

___

第二部分內容。

底線是最少人用的寫法，但同樣有效，所有主流 Markdown 解析器都支援。

語法規則詳解

雖然寫法簡單，但有幾條規則必須遵守，不然分割線可能顯示不出來，甚至變成別的東西。

必須單獨佔一行

分割線所在的那一行只能有分割線字元（前後可以有空格），不能有其他文字：

<!-- 正確 -->
一些文字

---

更多文字

<!-- 錯誤：同一行有其他文字 -->
--- 這不是分割線

前後要留空行

這一點特別重要。--- 在某些情況下會被解析器當作二級標題的底線（Setext 風格標題），而不是分割線：

<!-- 這會變成 H2 標題，不是分割線！ -->
一些文字
---

<!-- 這才是分割線 -->
一些文字

---

更多文字

我之前在寫一個專案的 CHANGELOG 時就踩過這個坑——版本號下面緊接著 ---，結果版本號變成了大標題，分割線反倒沒了。解決辦法很簡單：在 --- 上面加一個空行。

不能混用不同字元

每一行的分割線只能用同一種字元，混著寫是不行的：

<!-- 錯誤：混用了短橫線和星號 -->
--*
-*-

<!-- 正確：只用一種字元 -->
---

至少三個字元

兩個字元不夠，必須三個或以上：

<!-- 錯誤：只有兩個 -->
--

<!-- 正確：三個或更多 -->
---
-----

不同平台的渲染差異

雖然所有主流平台都支援這三種寫法，但渲染出來的樣式略有不同：

用 HTML <hr> 標籤作為替代

如果 Markdown 的分割線語法不生效（比如某些特殊環境），可以直接用 HTML 的 <hr> 標籤：

一些文字

<hr>

更多文字

大多數支援 Markdown 的平台也支援行內 HTML，所以 <hr> 基本都能用。效果和 Markdown 語法一樣。

自訂分割線樣式

Markdown 本身不支援樣式定製，但如果你用的平台允許 HTML 和 CSS，可以透過幾種方式來美化分割線。

行內樣式

直接在 <hr> 標籤上加 style 屬性：

<hr style="border: 2px solid #333; width: 60%; margin: 2em auto;">

這會渲染出一條深灰色、寬度為頁面 60%、置中的分割線。GitHub 和大部分靜態網站產生器都支援這種寫法。但 Obsidian 的即時預覽和一些會過濾 HTML 的編輯器可能不支援。

全域 CSS

如果你有自己的網站或部落格，最好在 CSS 裡統一定義分割線樣式，而不是每個地方都寫行內樣式：

hr {
  border: none;
  border-top: 2px dashed #ccc;
  margin: 2em 0;
}

這樣 Markdown 裡所有的 --- 都會自動套用這個樣式。

markdown-it 自訂渲染

如果你用 Eleventy、VuePress 這類基於 markdown-it 的靜態網站產生器，可以透過覆寫渲染規則來完全自訂 <hr> 的輸出。

const markdownIt = require("markdown-it")
const mdSetup = markdownIt()

mdSetup.renderer.rules.hr = (tokens, idx, options, env, self) => {
  return '<hr class="custom-divider" />'
}

這樣所有 Markdown 裡的分割線都會渲染成帶 custom-divider 類別名稱的 <hr> 標籤，你可以用 CSS 隨意美化它。

分割線的實際使用場景

分割線用對了地方能讓文件更有條理，用多了反而顯得亂。以下是一些適合用分割線的場景：

專案介紹和功能描述...

---

## 更新日誌

### v2.0.0

- 新增了使用者管理功能
- 修復了登入逾時問題

---

### v1.0.0

- 初始版本發布

• README 的章節之間：把安裝說明和使用說明隔開
• 更新日誌的版本之間：每個版本條目前後用分割線
• 正文和附錄/註腳之間：區分主體內容和補充資訊
• 主題切換的地方：兩個完全不相關的話題之間

對了，如果每兩三個段落就插一條分割線，那說明你可能應該用標題來分節，而不是分割線。分割線適合用在標題不太合適、但又需要一個明顯視覺間隔的地方。

三種寫法該選哪個？

說實話，選哪個都行，一致性比具體選哪個更重要。我的建議是：

我個人一直用 ---，只要記住上面加個空行就沒事。如果你在給團隊寫編碼規範，*** 是最安全的選擇，因為它完全消除了和標題混淆的可能性。

常見問題

為什麼我的 --- 變成了標題？

因為 --- 緊接在文字下面時，會被解析為 Setext 風格的二級標題。在上面加一個空行就能解決。

兩個短橫線 -- 能做分割線嗎？

不能。至少需要三個。兩個短橫線在某些解析器裡是刪除線或破折號，和分割線無關。

分割線能加顏色或改粗細嗎？

純 Markdown 不行。但如果你用的平台支援 HTML，可以用帶樣式的 <hr> 標籤實現，或者在網站的 CSS 裡統一修改。

分割線和空行有什麼區別？

空行只是增加段落間距，分割線會渲染出一條可見的橫線。如果你只需要段落間距，用空行就夠了，不需要分割線。

Discord 和 Slack 為什麼不支援分割線？

這兩個平台的 Markdown 支援是有限的子集，它們沒有實作 thematic break 語法。在 Discord 和 Slack 裡，你只能用 emoji（比如 ————— 或 - - -）來模擬分割線的效果。

參考來源

• CommonMark Spec 0.31.2 - Thematic Breaks
• GitHub - markdown-guide horizontal-rules