Markdown 标题语法

6 min入门

ATX 与 Setext 两种标题写法、空格与闭合序列等解析规则、层级规划与目录生成。

认知导入（Layer 0 生存层） 前置知识：无需前置，直接开始。 边界说明：学完本节你能写出层级分明的标题；学不会，后续所有文档的结构都会乱。 强制练习：打开编辑器输入 # 你好 和 ## 小节，观察标题大小；再把 # 后面的空格删掉，观察标题是否失效——空格是语法的一部分。

1. 两种标题风格

Markdown 支持两种标题写法：ATX 风格（用 #）与 Setext 风格（用下划线行）。ATX 是主流写法，Setext 偶尔见于手写文档。

1.1 ATX 风格（井号标题）

# 的数量对应标题级别，共六级：

# 一级标题（对应 HTML h1）
## 二级标题（对应 HTML h2）
### 三级标题（对应 HTML h3）
#### 四级标题（对应 HTML h4）
##### 五级标题（对应 HTML h5）
###### 六级标题（对应 HTML h6）

Markdown 没有七级标题：再多写井号（#######）不会被识别为标题，会按普通段落渲染。

1.2 Setext 风格（下划线标题）

在标题文本的下一行写一串 = 或 -，分别对应一级和二级标题：

一级标题（下一行写等号）
=====

二级标题（下一行写短横线）
-----

Setext 只支持两级，且下划线行的长度不必与文本一致（一个字符也可以）。但要注意一个高频陷阱：- 下划线紧跟在普通段落文本之后时，会被解析成 Setext 二级标题而不是别的元素。例如：

Hello
---

渲染出来是二级标题 “Hello”，而不是一条水平分隔线。想要分隔线，必须在上文与 --- 之间留一个空行（空行后 --- 才是水平线）。

2. ATX 标题的解析规则

2.1 井号后必须有空格

# 与标题文本之间的空格是语法的一部分：

# 正确写法（井号后有空格）
#错误写法（井号后无空格，按普通文本渲染）

个别渲染器（如某些编辑器插件）对无空格写法宽容，但 CommonMark/GFM 均要求空格，跨平台写作一律加上。

2.2 可选的闭合序列

ATX 标题允许在末尾写一串井号”闭合”，渲染时会被剥离：

## 二级标题 ##

渲染为二级标题”二级标题”。闭合序列的规则有三条：

  • 闭合井号前必须有空格：## 二级标题## 中的尾部井号属于标题文本，不会被剥离。
  • 闭合序列之后只能有空白：## 标题 ## 注释 不是标题。
  • 闭合井号数量不必与开头相同：# 标题 ### 合法。

2.3 层级数量与缩进

  • 前导空格最多 3 个， # 标题 仍是标题；4 个及以上会变成代码块。
  • 井号数量超过 6（如 #######）不构成标题。
  • 标题可以打断段落（中间不需要空行），但推荐标题前后保留空行，源码更易读。

2.4 三个易漏的边界

井号后跟数字不是标题。CommonMark 要求 # 之后必须是空格或行尾，#5 号更新 会按普通文本渲染——写话题标签式内容时留意。

#5 号更新     <!-- 不是标题，是普通文本 -->
# 5 号更新    <!-- 井号后有空格，是一级标题 -->

空标题合法。##（只有井号）会渲染出一个空的 <h2>，不报错但污染文档大纲，提交前应清理。

标题文本内可以放行内格式。代码、加粗、链接都能出现在标题里，并参与锚点生成（这会让自动锚点变得难看，命名时尽量用纯文本）：

## 使用 `npm run` 脚本    <!-- 标题里含行内代码 -->

3. Setext 标题的补充规则

Setext 下划线（= 或 - 行）有三条容易被忽略的规则：

  • 下划线行可以缩进 1-3 空格，与 CommonMark 的块级前导空格规则一致；
  • 文本行不能是”懒延续”的段落：如果上一行是列表项或引用的延续内容，--- 会被优先解析为该结构的组成部分而非标题下划线；
  • = 行几乎无歧义，- 行歧义最大（与列表标记、分隔线共用字符），所以实践中 Setext 基本只用 = 写一级标题，或干脆不用 Setext。

4. 渲染效果对照

源码渲染结果HTML 对应典型用途
# 标题最大的标题<h1>文档主标题
## 标题大标题<h2>主要章节
### 标题中标题<h3>子章节
#### 标题小标题<h4>更细分节
##### 标题更小标题<h5>少用
###### 标题最小标题<h6>少用

同一个文档实际渲染效果：

# Markdown 标题语法
## ATX 风格
### 基本写法

预览时会看到从大到小的三级字号；多数平台还会根据标题自动生成目录锚点（见 markdown/200-AutoTOC）。

5. 标题层级规划

5.1 使用原则

  1. 一级标题只用一次：作为文档主标题。GitHub 的 README、本站的教程页都遵循这一惯例；部分文档平台（如 MkDocs）甚至要求正文从二级标题开始。
  2. 逐级递进，不跳级：## 之下接 ###，不要从 ## 直接跳到 ####。跳级会破坏文档大纲（outline），影响屏幕阅读器导航与自动目录的层级结构。
  3. 不依赖标题控制字号：标题是结构语义，不是视觉字号。觉得 ### 太大就去改样式，而不是改用 ##### 凑合。

5.2 命名建议

  • 简洁、名词或动宾短语优先，长度控制在单行以内。
  • 同一文档内标题风格一致（全部中英混排或全部中文）。
  • 标题文本会成为页内锚点的一部分，命名时考虑链接引用（详见 markdown/190-AnchorLinks）。

6. 常见问题与排查

6.1 标题不生效

  • # 后缺少空格（最常见）；
  • 行首缩进达到 4 个空格，整行被识别为代码块；
  • 井号数量超过 6 个。

6.2 --- 变成了标题

上文段落与 --- 之间没有空行，--- 被解析为 Setext 二级标题下划线。在两者之间插入空行即可恢复”水平分隔线”语义。

6.3 目录里出现乱码或重复

标题含代码、标点或重复文本时，自动锚点会做转换或追加序号，导致目录链接与预期不同。排查与规避见 markdown/190-AnchorLinks。

6.4 文档大纲出现空层级或跳级

空标题（只有井号）与跳级（## 下直接 ####）都会让文档大纲（outline）出现空洞或断层，屏幕阅读器与自动目录最受影响。提交前的自检清单：唯一 H1、无空标题、层级逐级递进。

小结

  • 初学者要点：日常写作只需要 # 到 ### 三级；# 后必须加空格；一级标题全文一次；层级逐级递进。
  • 进阶注意：ATX 支持可选闭合序列（## 标题 ##），闭合前必须有空格；Setext 只有两级，且段落文本后的 --- 会变成 Setext 标题而不是分隔线；标题是结构语义，勿用它调字号。