Markdown: Markdown 标题语法与层级规范
标题是文档的骨架——它告诉读者和搜索引擎你的内容是怎么组织的。
1. 你将学到
- Markdown 的两种标题语法：ATX 和 Setext
- 六级标题的正确使用方式
- 标题层级规范与最佳实践
- 常见标题错误及修正方法
- 标题对 SEO 和可访问性的影响
2. 一个文档维护者的真实故事
(1) 痛点：混乱的标题层级
Sarah 接手了一个技术博客项目，发现过去的文章标题使用很随意——有的用 #，有的用 ##，有的文章直接没有标题，还有的文章跳过了二级标题从一级直接跳到三级。结果网站的目录生成器完全无法工作，读者反馈找不到内容。
(2) 解法：统一标题规范
Sarah 制定了标题使用规则：每篇文章只有一个 # 标题，按 ## → ### → #### 逐级递进，不跳级。她用一个脚本批量修正了全部 50 篇文章。修正后，网站自动目录正常工作，读者在页面内的停留时间提升了 40%。
3. 标题的两种语法
Markdown 提供两种标题语法：
graph TB
A[Markdown 标题] --> B[ATX 风格]
A --> C[Setext 风格]
B --> D[# 到 ######]
B --> E[最常用]
C --> F[=== 和 ---]
C --> G[仅限 H1 和 H2]
| 语法 | 写法 | 支持级别 | 推荐场景 |
|---|---|---|---|
| ATX | # 到 ###### |
H1-H6 | 所有场景，通用性强 |
| Setext | === / --- |
仅 H1、H2 | 少数编辑器偏好，兼容性差 |
(1) ATX 风格（推荐）
ATX 风格用 # 符号的数量表示标题级别，一个 # 表示一级标题，两个 ## 表示二级，以此类推：
MARKDOWN
# 一级标题（H1）
## 二级标题（H2）
### 三级标题（H3）
#### 四级标题（H4）
##### 五级标题（H5）
###### 六级标题（H6）
💡 提示：
# 后面必须跟一个空格再写标题文字，否则某些解析器不会识别为标题。
(2) Setext 风格
Setext 风格用 === 或 --- 放在标题文字下方：
MARKDOWN
一级标题
=======
二级标题
-------
⚠️ 注意： Setext 风格只支持 H1 和 H2 两级标题。在 GitHub 和其他 GFM 解析器中工作正常，但某些小众解析器可能不支持。建议仅在兼容性好且需要风格变化时使用。
▶ 示例：两种标题风格对比
MARKDOWN
# ATX 风格 H1
ATX 风格 H2
============
注意：上面的下面有 ===，在渲染时会显示为 H1
4. 标题层级规范
(1) 正确使用层级
文档标题应当像书籍目录一样有清晰的层次结构：
MARKDOWN
# 文档标题（只有一个 H1）
## 第 1 章（H2）
### 1.1 小节（H3）
#### 1.1.1 子小节（H4）
### 1.2 小节（H3）
## 第 2 章（H2）
⚠️ 注意： 不要跳级！H2 后面直接跟 H4 会让目录结构断裂。如果内容不需要三级标题，保持
H2 → H2 同级也没问题。
(2) SEO 与可访问性影响
标题层级对 SEO 和屏幕阅读器至关重要：
| 方面 | 推荐做法 | 避免做法 |
|---|---|---|
| H1 数量 | 每页仅一个 | 多个 H1 混淆搜索引擎 |
| 关键词 | H1 含核心词，H2 含相关词 | 堆砌关键词 |
| 层级 | 逐级递进，不跳级 | H1→H3→H2 混乱 |
| 长度 | H1 ≤60 字符，H2 ≤40 字符 | 整段文字作标题 |
▶ 示例：正确 vs 错误的标题层级
MARKDOWN
✅ 正确：
# CSS 布局教程
## Flexbox
### Flex 容器属性
### Flex 项目属性
## Grid
### Grid 容器属性
❌ 错误：
# CSS 布局教程
### Flex 容器属性（跳过了 H2）
## Flexbox
#### Flexbox 属性详解（H3→H4 不自然）
## Grid
💡 提示： 你可以把 H1 想象成一本书的书名，H2 是章节名，H3 是章节内的小节——这个类比能帮你自然地维护层级。
5. 标题中的格式与特殊字符
(1) 标题中可以加粗、斜体、代码
MARKDOWN
## 使用 `npm install` 安装依赖
## 理解 **flex-grow**、**flex-shrink** 和 **flex-basis**
## 什么是 *响应式设计*？
(2) 标题中避免的长内容
MARKDOWN
❌ 避免：
## 这是一篇关于如何使用 Python 的 requests 库来发送 HTTP 请求的详细教程
✅ 推荐：
## 用 requests 库发送 HTTP 请求
💡 提示： 标题在目录和搜索结果中会被截断。保持标题清晰简短，让读者扫一眼就知道在讲什么。
▶ 示例：标题优化前后对比
MARKDOWN
❌ 太长：
## 这篇文章将教你如何在 Windows 系统上用 VS Code 配置 Python 开发环境
✅ 优化后：
## 在 VS Code 中配置 Python 环境
💡 提示： 把详细说明放到正文段落中，标题只保留核心关键词。
6. 完整示例：一篇文章的标题结构
MARKDOWN
# 使用 Python 进行数据分析
## 1. 数据准备
### (1) 导入库
### (2) 读取数据
### ▶ 示例：读取 CSV 文件
## 2. 数据清洗
### (1) 处理缺失值
### ▶ 示例：填充空值
### (2) 去除重复数据
## 3. 数据可视化
### (1) 折线图
### ▶ 示例：绘制趋势图
### (2) 柱状图
预期效果：一个层次分明的文档结构，读者和搜索引擎都能快速理解内容组织方式。
❓ 常见问题
Q 一篇文章可以有多个 H1 吗？
A 技术上可以，但强烈不推荐。文章只有一个 H1（通常是标题），多个 H1 会让搜索引擎混淆哪个是主要内容。
Q 标题末尾要不要加句号？
A 不加。标题不是完整句子，末尾不加标点。FAQ 的 Q 部分可以加问号，因为它是问句。
Q
# 和标题文字之间的空格必须吗？A 必须。
#Title 不会被识别为标题，会被当作普通文字。# Title 才是正确写法。Q 标题可以用中文吗？
A 可以。但 URL 锚点会以英文方式生成。如果需要稳定锚点，可以在标题后加
{#custom-id} 自定义 ID。Q H5 和 H6 很少用，它们有意义吗？
A 有。在深层嵌套的技术文档（如法律条款、API 参数说明）中会用。但普通文章一般到 H3 或 H4 就够了。
📖 小节
- 两种标题语法：ATX（
#）和 Setext（===），推荐全程使用 ATX #后必跟空格，否则不被识别为标题- 每页仅一个 H1，逐级递进不跳级
- 标题保持简短（H1 ≤60 字符），避免堆砌关键词
- 标题中可包含代码、加粗、斜体等格式
- 良好的标题层级同时服务读者和搜索引擎
📝 作业
-
基础题：写一篇包含 H1、H2、H3 三层标题的 Markdown 短文，标题内容自定（如读书笔记或学习计划）。确保每一级标题只比上一级多一个
#。 -
进阶题：打开你最近写的一篇文档，检查它的标题层级是否规范。如果有跳级或混乱的情况，修正它。然后数一数你用了几个 H1（正确答案是 1 个）。
-
挑战题：用 VS Code 的 Markdown All in One 扩展生成文档目录（输入
[TOC]或使用命令），验证你的标题层级是否正确。如果生成的目录有异常，说明标题层级需要调整。
