Markdown 標題語法

寫 Markdown 文件，標題（headers/headings）是用得最多的元素之一。不管你寫 README、技術部落格還是專案文件，標題都是組織內容結構的基本手段。這篇文章把 Markdown 標題語法的方方面面講清楚——不只是「怎麼寫」，還有「為什麼這麼寫」和「哪些地方容易踩坑」。

Markdown 標題的基本寫法

Markdown 支援兩種標題風格：ATX 風格和 Setext 風格。ATX 是絕大多數人在用的方式，Setext 則比較少見但仍然有效。

ATX 風格：用 # 號建立標題

ATX 風格就是在行首用 1 到 6 個 # 號來表示標題級別，對應 HTML 的 <h1> 到 <h6>：

## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題

渲染效果就是從大到小六個級別的標題，一級最大最粗，六級最小。

幾個需要注意的事項：

  • # 號和標題文字之間必須有空格。寫成 #標題 在很多渲染器裡不會生效，只會被當成普通文字。說實話這是我自己剛開始用 Markdown 時踩過最多的坑——明明寫了 #，為什麼渲染出來不是標題？就是因為少了那個空格。
  • # 號數量決定標題級別，1 個 # 是一級（h1），6 個 # 是六級（h6）。
  • 你可以在標題文字後面加上任意數量的 # 作為「閉合」，但這是可選的，加了也不影響渲染結果：
## 這是一個二級標題 ##
### 後面的 # 號可有可無 ###

Setext 風格：用底線建立標題

Setext 風格只支援一級和二級標題，寫法是在文字下方加等號（=）或破折號（-）：

這是一級標題
=============

這是二級標題
-------------

等號表示一級標題，破折號表示二級標題。底線的數量不限，寫一個也行，寫滿一行也行，效果一樣。

Setext 風格在純文字裡可讀性很好——看起來就像傳統文件裡用底線標註標題的效果。不過在大多數現代 Markdown 教學和工具中，ATX 風格更常見。我的建議是：如果你只是寫文件，統一用 ATX 風格就好，簡單不容易搞混。Setext 知道就行，遇到別人的文件能看懂。

兩種風格對比

對比項ATX 風格Setext 風格
支援級別h1 到 h6僅 h1 和 h2
語法# 號前綴= 或 - 底線
可讀性原始碼中一眼看出級別純文字中更像傳統標題
流行度最主流較少使用
編輯便利性增刪 # 即可改級別需要增刪整行底線

Markdown 標題級別該怎麼用

了解了語法，更重要的問題是：六級標題該怎麼用才合理？這涉及到文件結構、SEO 和無障礙訪問。

標題級別的語意

標題級別不只是「字號大小」，它代表的是文件的層級結構。在 HTML 中，<h1> 到 <h6> 構成了頁面的大綱，搜尋引擎和螢幕閱讀器都依賴這個結構來理解內容。

一個好的標題結構應該是：

# 文件標題（h1）
## 第一部分（h2）
### 第一部分的某個子話題（h3）
### 第一部分的另一個子話題（h3）
## 第二部分（h2）
### 第二部分的子話題（h3）

而不應該跳級，比如 h1 直接跳到 h3：

# 文件標題（h1）
### 直接跳到三級標題？❌

雖然語法上不會報錯，但跳級會讓文件結構混亂，對 SEO 和無障礙訪問都不友善。

實際使用建議

  • 一個文件通常只有一個 h1。它就是文件的主標題，相當於書的書名。
  • h2 用來劃分大章節，相當於書的章。
  • h3 用來劃分小節，相當於章下面的節。
  • h4 到 h6 按需使用，大多數文件用不到那麼深的層級。

有一次我幫一個專案整理文件，發現他們直接從 h1 跳到了 h4——因為「覺得 h4 的字號大小剛好合適」。這其實是搞混了標題的語意用途和視覺效果。標題級別反映的是內容結構，字號應該透過 CSS 來控制。

標題的錨點與頁內跳轉

在很多 Markdown 渲染環境中，標題會自動生成錨點（anchor），你可以用連結直接跳轉到某個標題位置。

GitHub 和大多數平台的預設行為

在 GitHub、GitLab 等平台上，標題會自動生成一個 ID，規則是：將標題文字轉為小寫、去掉特殊字元、空格變成連字符。比如：

## Markdown 標題語法

自動生成的錨點是 #markdown-標題語法。在 GitHub 上，中文標題的錨點處理方式可能和純英文不太一樣，如果需要精確跳轉，最好在瀏覽器中檢查一下實際的錨點值。

自訂標題 ID

有些 Markdown 擴充語法支援自訂標題 ID，比如 Pandoc 和 PHP Markdown Extra：

## 我的標題 {#custom-id}

這樣你就可以用 [跳轉到我的標題](#custom-id) 來建立頁內連結了。

不同渲染器的相容性差異

Markdown 最大的「坑」之一就是不同渲染器對同一語法的處理可能不一樣。標題語法雖然相對簡單，但也有差異。

空格問題

# 後面加空格這件事，不同渲染器的寬容度不同：

渲染器#標題（無空格）# 標題（有空格）
CommonMark❌ 不識別✅ 正常渲染
GFM（GitHub）❌ 不識別✅ 正常渲染
舊版 Markdown.pl部分識別✅ 正常渲染
markdown-it❌ 不識別✅ 正常渲染

結論很簡單：永遠加空格，不用糾結。

標題前後的空行

在大多數渲染器中，標題前後不需要空行就能正確識別。但在一些實作中（比如 Flexmark 解析器），標題前面緊挨著程式碼區塊、列表或引用時，可能會被誤解析。穩妥的做法是標題前後各留一個空行。

Setext 風格的支援度

雖然 Setext 是原始 Markdown 規範的一部分，但有些輕量級 Markdown 解析器不支援它。如果你確定目標平台支援（比如 GitHub、GitLab、CommonMark 相容的渲染器），用 Setext 沒問題。如果不確定，還是用 ATX。

常見問題

Markdown 標題最多有幾級？

六級，對應 ######（6 個 # 號加空格）。HTML 規範中 <h1> 到 <h6> 也只有六個級別。實際寫作中，大多數文件用到 h3 或 h4 就足夠了。

為什麼我的 # 標題沒有渲染？

最常見的原因是 # 後面沒有加空格。確保寫成 # 標題 而不是 #標題。另一個可能的原因是 # 前面有縮排空格——標題的 # 必須在行首（前面可以有三個以內的空格，但最好不要有）。

ATX 和 Setext 哪個更好？

ATX 更實用——它支援六個級別、編輯方便（增刪 # 就能改級別）、也更主流。Setext 的優勢是在純文字環境下可讀性好，但只支援兩級標題。除非你有特殊偏好，建議統一用 ATX。

標題可以用粗體或斜體嗎？

可以。標題文字中可以包含行內格式：

## **重點**章節
### 這個功能 *已經廢棄*

不過從寫作習慣來說，標題本身已經是強調元素了，加粗體有些多此一舉，按需使用。

參考來源