Markdown 语法指南
00:00
24 min Beginner 2026/4/5
markdown

Markdown 概述与核心特点。

1. 引言

Markdown 是一种轻量级标记语言，使用纯文本格式编写文档，具有语法简洁、可读性强、跨平台兼容等特点。它允许人们使用易读易写的纯文本格式编写文档，然后转换为结构完整的 HTML 文档或其他格式。

1.1. Markdown 特点

  • 简单易用：语法简洁明了，学习成本低
  • 跨平台兼容：几乎所有现代文本编辑器都支持
  • 可读性强：纯文本也具有良好的结构和可读性
  • 灵活性高：支持嵌入 HTML 代码，扩展功能
  • 广泛应用：GitHub、GitLab、Bitbucket 等平台都支持
  • 可转换性：可以转换为 HTML、PDF、EPUB 等多种格式

1.2. Markdown 发展历史

年份事件
2004John Gruber 和 Aaron Swartz 创建 Markdown
2007CommonMark 规范开始制定
2014GitHub Flavored Markdown (GFM) 发布
2017CommonMark 1.0 规范发布
2020+各种 Markdown 扩展和工具不断涌现

2. 什么是 Markdown

Markdown 是一种轻量级标记语言，由 John Gruber 和 Aaron Swartz 在 2004 年创建。它的设计目标是让人们能够使用易读易写的纯文本格式编写文档，然后可以轻松转换为结构完整的 HTML 文档。

2.1. Markdown 的核心设计理念

  • 可读性：Markdown 文档本身就是易读的纯文本，即使不转换为其他格式也能清晰理解
  • 简洁性：语法简单明了，学习成本低，容易上手
  • 可扩展性：支持嵌入 HTML 代码，可以实现更复杂的功能
  • 平台无关：在任何支持纯文本的平台上都可以使用

2.2. Markdown 的应用场景

应用场景示例
项目文档README 文件、API 文档、技术规范
技术博客个人博客、技术社区文章
笔记整理个人学习笔记、会议记录、课程笔记
邮件撰写部分邮件客户端支持 Markdown 格式
电子书创作可以转换为 PDF、EPUB 等格式
文档网站使用静态站点生成器创建文档网站
代码注释部分代码仓库使用 Markdown 编写注释
知识库企业内部知识库、wiki 系统

2.3. Markdown 与其他标记语言的比较

标记语言特点适用场景
Markdown简洁易用，可读性强日常文档、博客、笔记
HTML功能强大，结构完整网页开发、复杂文档
reStructuredText功能丰富，语法严谨Python 文档、技术文档
AsciiDoc功能全面，语义丰富大型技术文档、手册
LaTeX专业排版，数学公式支持学术论文、书籍

3. 标题语法

Markdown 支持 6 级标题，通过 # 的数量区分层级，# 后必须加 1 个空格，否则语法不生效。

3.1. 语法示例

# 一级标题（对应 HTML h1，文档主标题）

## 二级标题（对应 HTML h2，一级章节）

### 三级标题（对应 HTML h3，二级章节）

#### 四级标题

##### 五级标题

###### 六级标题

3.2. 渲染效果

一级标题

二级标题

三级标题

四级标题

五级标题
六级标题

3.3. 标题使用建议

  • 层级清晰：合理使用标题层级，一般不超过 4 级
  • 语义明确：标题应该准确反映章节内容
  • 一致性：保持标题风格一致，避免混用不同的标题格式
  • 简洁明了：标题应该简洁明了，避免过长

4. 段落与换行

4.1. 核心规则

  1. 段落分隔：两个段落之间必须用1 个空行分隔，无空行的连续文本会被合并为同一段落
  2. 强制换行：行尾添加2 个及以上空格后按回车，实现同一段落内的换行（全平台通用标准写法）

4.2. 语法示例

这是第一个段落的第一行
这一行和上一行无空行、无行尾空格，会被合并为同一段落
这是第二个段落（上一行是空行，成功分段）
这一行末尾加了 2 个空格
这一行成功换行，和上一行属于同一段落

4.3. 渲染效果

这是第一个段落的第一行 这一行和上一行无空行、无行尾空格，会被合并为同一段落 这是第二个段落（上一行是空行，成功分段） 这一行末尾加了 2 个空格 这一行成功换行，和上一行属于同一段落

4.4. 段落格式建议

  • 段落长度：保持段落简短，每段不超过 3-4 行，提高可读性
  • 空行使用：在不同语法元素之间添加空行，如标题与段落之间、段落与列表之间
  • 缩进：一般情况下不需要缩进段落，特殊情况（如引用内的段落）除外

5. 基础文本格式

5.1. 核心语法

格式效果语法写法渲染效果
斜体*斜体文本* 或 _斜体文本_斜体文本
粗体**粗体文本** 或 __粗体文本__粗体文本
粗斜体***粗斜体文本*** 或 ___粗斜体文本___粗斜体文本
删除线 (GFM 扩展)~~删除线文本~~删除线文本
下划线 (HTML)<u>下划线文本</u>下划线文本
高亮 (GFM 扩展)==高亮文本====高亮文本==
脚注 (GFM 扩展)[^脚注] 并在文档末尾定义 [^脚注]: 脚注内容1

5.2. 语法示例

这是*斜体*、**粗体**、**_粗斜体_**、~~删除线~~文本
HTML 支持的<u>下划线</u>格式
GFM 扩展的==高亮==功能
脚注示例[^1]
[^1]: 这是脚注内容

5.3. 文本格式使用建议

  • 适度使用：不要过度使用文本格式，以免影响可读性
  • 一致性：在同一文档中保持文本格式的一致性
  • 语义化：根据内容的重要性选择合适的文本格式
  • 避免嵌套：尽量避免过多嵌套的文本格式，如 粗斜体 已经足够

6. 列表语法

6.1. 无序列表

使用 -/*/+ + 空格开头，三者效果完全一致，推荐统一使用 -，嵌套列表需缩进4 个空格/1 个制表符。

7.1.1 语法示例

-
-

- 无序列表二级嵌套项 1
- 无序列表二级嵌套项 2
- ## 无序列表三级嵌套项

7.1.2 渲染效果

  • 无序列表一级项 1
  • 无序列表一级项 2
  • 无序列表二级嵌套项 1
  • 无序列表二级嵌套项 2
  • 无序列表三级嵌套项
  • 无序列表一级项 3

6.2. 有序列表

使用 数字 + 英文句号 + 空格 开头，数字顺序不影响最终渲染结果，推荐按顺序书写，嵌套需缩进4 个空格/1 个制表符。

7.2.1 语法示例

1.  有序列表一级项 1
2.  有序列表一级项 2
3.  有序列表二级嵌套项 1
4.  有序列表二级嵌套项 2
5.  有序列表一级项 3

7.2.2 渲染效果

  1. 有序列表一级项 1
  2. 有序列表一级项 2
  3. 有序列表二级嵌套项 1
  4. 有序列表二级嵌套项 2
  5. 有序列表一级项 3

6.3. 任务列表

待办清单专用语法（GFM 扩展），[ ] 表示未完成，[x] 表示已完成，符号后必须加空格。

7.3.1 语法示例

-
-
-

- [x] 子任务 1
- [ ] 子任务 2

7.3.2 渲染效果

  • 未完成的待办任务
  • 已完成的待办任务
  • 可嵌套待办
  • 子任务 1
  • 子任务 2

6.4. 列表使用建议

  • 嵌套层级：嵌套列表不要超过 3 层，以免影响可读性
  • 空行：在列表项之间添加空行，提高可读性
  • 内容长度：列表项内容不要过长，必要时可以拆分为多个列表
  • 一致性：在同一文档中使用一致的列表标记符

7. 块引用

使用 > + 空格开头，可多层嵌套，也可与标题、列表、代码等其他语法混用。

7.1. 语法示例

>

7.2. 渲染效果

单层块引用，多行内容可只在第一行加> 第二行内容，和上一行同属一个引用块 多层嵌套引用

第二层嵌套引用

第三层嵌套引用 引用内混用其他语法

  1. 有序列表项
  2. 有序列表项 粗体文本

7.3. 块引用使用建议

  • 适度使用：不要过度使用块引用，以免文档结构混乱
  • 嵌套层级：嵌套引用不要超过 3 层
  • 内容相关性：引用的内容应该与上下文相关
  • 来源标注：如果引用的是他人的内容，应该标注来源

8. 分隔线

使用 3 个及以上的 -/*/_ 单独占一行，前后建议保留空行，避免与二级标题语法混淆。

8.1. 语法示例

- \
  \

8.2. 渲染效果

8.3. 分隔线使用建议

  • 适度使用：分隔线用于分隔不同的内容区块，不要过度使用
  • 位置：分隔线应该放在逻辑上需要分隔的内容之间
  • 一致性：在同一文档中使用一致的分隔线风格

9. 链接语法

9.1. 行内式链接

标准格式：[链接显示文本](链接地址 "链接可选标题")

  • 可选标题：鼠标悬浮时显示的提示文字，可省略

10.1.1 语法示例

[GitHub 官网](https://github.com '全球最大开源托管平台')
[打开豆包](https://www.doubao.com)

10.1.2 渲染效果

GitHub 官网 打开豆包

9.2. 自动链接

用 <> 包裹网址/邮箱，快速生成链接，适合直接展示完整地址。

10.2.1 语法示例

<https://github.com>
<fanquanpangpiing@163.com>

10.2.2 渲染效果

https://github.com fanquanpangpiing@163.com

9.3. 参考式链接

适合长文档中多次复用同一个链接，文档末尾统一定义地址，便于维护。

10.3.1 语法示例

[GitHub 官网][github]
[GitHub 开源社区][github]

 <!-- 文档末尾统一定义 -->

[github]: https://github.com 'GitHub 官网'

10.3.2 渲染效果

[GitHub 官网][github] [GitHub 开源社区][github] [github]: https://github.com “GitHub 官网”

9.4. 链接使用建议

  • 链接文本：使用有意义的链接文本，避免使用”点击这里”等模糊描述
  • 参考式链接：在长文档中使用参考式链接，提高可维护性
  • 链接检查：定期检查链接是否有效，避免链接失效
  • 相对路径：在项目文档中使用相对路径，确保跨平台兼容性

10. 图片语法

基础格式：![图片替代文本](图片地址 "图片可选标题")

  • 替代文本：图片加载失败时显示的文字，必填
  • 可选标题：鼠标悬浮时显示的提示文字，可省略

10.1. 语法示例

!

10.2. 图片带跳转链接

嵌套链接语法，实现点击图片跳转到指定地址。

[![示例图片](https://example.com/image.jpg)](https://github.com)

10.3. 本地图片

使用相对路径引用本地图片，适合项目文档。

!

10.4. 图片使用建议

  • 替代文本：为图片添加有意义的替代文本，提高可访问性
  • 图片尺寸：合理控制图片尺寸，避免图片过大影响加载速度
  • 图片格式：选择合适的图片格式，如 JPG、PNG、SVG 等
  • 图片路径：使用相对路径引用图片，确保跨平台兼容性

11. 代码语法

11.1. 行内代码

用单个反引号 ` 包裹，适合在行内插入短代码、关键词、命令。

12.1.1 语法示例

Python 的打印函数是`print("Hello World")`

12.1.2 渲染效果

Python 的打印函数是print("Hello World")

11.2. 多行代码块

用三组反引号 ``` 包裹，上下单独占一行，支持指定编程语言实现语法高亮。

12.2.1 语法示例

```python
# Python 代码示例
def hello_markdown():
print("Hello Markdown!")
return 0
```

#### 12.2.2 渲染效果
```python
# Python 代码示例
def hello_markdown():
 print("Hello Markdown!")
 return 0

11.3. 代码语法使用建议

  • 语言指定：为代码块指定编程语言，启用语法高亮
  • 代码缩进：保持代码的缩进和格式，提高可读性
  • 代码注释：为复杂代码添加注释，解释代码功能
  • 命令示例：提供完整的命令示例，包括输入和输出
  • 代码长度：对于过长的代码，考虑只展示关键部分，或提供链接

12. 表格语法

使用 | 分隔单元格，- 分隔表头和表体，: 定义列对齐方式（GFM 扩展）：

  • 左对齐：:---（默认）
  • 居中对齐：:---:
  • 右对齐：---:

12.1. 语法示例

| 左对齐列   | 居中对齐列 | 右对齐列 |
| :--------- | :--------: | -------: |
| 内容 1     |   内容 2   |   内容 3 |
| 长文本测试 |  居中显示  | 靠右显示 |

12.2. 渲染效果

左对齐列居中对齐列右对齐列
内容 1内容 2内容 3
长文本测试居中显示靠右显示

12.3. 表格使用建议

  • 表格内容：表格内容应该简洁明了，避免过于复杂
  • 列数：表格列数不宜过多，一般不超过 5 列
  • 对齐方式：根据内容类型选择合适的对齐方式，如数字右对齐
  • 空行：在表格前后添加空行，提高可读性

13. 转义字符

使用反斜杠 \ 转义 Markdown 特殊字符，使其正常显示，避免被解析为语法标记。

13.1. 可转义的核心特殊字符

\
\
\

# 井号

-

* . 英文句号
  !
  | 竖线
  ` 反引号
  [ ] 方括号
  ( ) 圆括号

13.2. 语法示例

\
\
\

13.3. 转义字符使用建议

  • 必要时使用：只在需要显示特殊字符时使用转义
  • 可读性：不要过度使用转义，以免影响代码可读性
  • 测试：在使用转义字符后，预览效果确保正确显示

14. 页内跳转（锚点链接）

实现文档内部标题之间的跳转，格式：[跳转显示文本](#目标标题名称)

14.1. 核心规则

  1. 标题名称全部转为小写
  2. 空格替换为短横线 -
  3. 特殊符号直接省略
  4. 多级标题直接拼接，如 ## 1.1 标题 对应 #11-标题

14.2. 语法示例

[跳转到文档开头](#markdown-语法指南)
[跳转到标题语法章节](#标题语法)
[跳转到无序列表](#无序列表)

14.3. 页内跳转使用建议

  • 目录：为长文档添加目录，使用页内跳转方便导航
  • 命名规范：确保标题名称清晰，便于生成锚点
  • 测试：在添加页内跳转后，测试跳转是否正常

15. 扩展语法

15.1. GitHub Flavored Markdown (GFM) 扩展

功能语法渲染效果
任务列表- [ ] 任务- [ ] 任务
代码块语法高亮```python

代码

 | **表格** | `| 列1 | 列2 |` | 表格 |
 | **删除线** | `~~文本~~` | ~~文本~~ |
 | **高亮** | `==文本==` | ==文本== |
 | **自动链接** | `<https://example.com>` | <https://example.com> |
 | **脚注** | `[^脚注]` | [^脚注] |
 ### 16.2 其他常见扩展
 | 功能 | 语法 | 适用平台 |
 |------|------|----------|
 | **数学公式** | `$$E=mc^2$$` | MathJax 支持的平台 |
 | **定义列表** | `术语
 :
 | **自动生成目录** | `[TOC]` | 部分 Markdown 处理器 |
 | **HTML 嵌入** | `<div>HTML 内容</div>` | 所有 Markdown 处理器 |
 | **图表** | ```mermaid
 图表定义
 ``` | Mermaid 支持的平台 |

### 15.3. 扩展语法使用建议
- **兼容性**：使用扩展语法时考虑平台兼容性
- **文档说明**：如果使用了扩展语法，在文档中说明需要的渲染环境
- **适度使用**：不要过度依赖扩展语法，保持文档的基本兼容性
## 16. 常见问题与解决方案
### 16.1. 语法标记问题
**问题描述**：标题、列表、引用等语法不生效。
**原因分析**：标记符后缺少空格。
**解决方案**：在标记符后添加一个空格，如 `# 标题`、`- 列表项`、`> 引用`。
### 16.2. 段落分隔问题
**问题描述**：文本无法正确分段。
**原因分析**：段落之间没有空行。
**解决方案**：在段落之间添加一个空行，实现正确分段。
### 16.3. 嵌套元素问题
**问题描述**：嵌套列表或引用显示异常。
**原因分析**：嵌套元素缩进不正确。
**解决方案**：使用 4 个空格或 1 个制表符进行缩进。
### 16.4. 特殊字符问题
**问题描述**：特殊字符被错误解析为 Markdown 语法。
**原因分析**：特殊字符没有转义。
**解决方案**：使用反斜杠 `\` 转义特殊字符，如 `\#`、`\*`。
### 16.5. 跨平台兼容性问题
**问题描述**：在不同平台上渲染效果不一致。
**原因分析**：使用了平台特定的扩展语法。
**解决方案**：优先使用标准 Markdown 语法，避免使用平台特定的扩展功能。
### 16.6. 图片显示问题
**问题描述**：图片无法正常显示。
**原因分析**：图片路径错误或网络问题。
**解决方案**：检查图片路径是否正确，确保图片可访问。
### 16.7. 链接失效问题
**问题描述**：链接点击后无法访问。
**原因分析**：链接地址错误或目标网站不可访问。
**解决方案**：检查链接地址是否正确，确保目标网站可访问。
## 17. 最佳实践
### 17.1. 语法风格
- **统一标记符**：在同一文档中使用一致的 Markdown 语法风格
- **标题层级**：合理使用标题层级，一般不超过 4 级
- **空行使用**：在不同语法元素之间添加空行，提高可读性
- **缩进规范**：使用 4 个空格进行缩进，保持代码整洁
- **标点符号**：使用英文标点符号，保持一致性
### 17.2. 内容组织
- **目录结构**：为长文档添加目录，便于导航
- **段落长度**：保持段落简短，每段不超过 3-4 行
- **逻辑顺序**：按照逻辑顺序组织内容，确保层次清晰
- **重点突出**：使用粗体、斜体等格式突出重要内容
- **过渡语句**：在不同章节之间添加过渡语句，使文档更连贯
### 17.3. 代码与命令
- **代码块**：对于代码和命令，使用代码块而非行内代码
- **语法高亮**：为代码块指定编程语言，启用语法高亮
- **代码注释**：为复杂代码添加注释，提高可读性
- **命令示例**：提供完整的命令示例，包括输入和输出
- **代码长度**：对于过长的代码，考虑只展示关键部分
### 17.4. 链接与图片
- **链接文本**：使用有意义的链接文本，避免使用"点击这里"
- **图片替代文本**：为图片添加有意义的替代文本
- **参考式链接**：在长文档中使用参考式链接，提高可维护性
- **图片路径**：使用相对路径引用图片，确保跨平台兼容性
- **链接检查**：定期检查链接是否有效
### 17.5. 文档管理
- **版本控制**：使用 Git 等版本控制系统管理 Markdown 文档
- **命名规范**：为文档文件使用清晰的命名规范
- **目录结构**：建立合理的文档目录结构
- **备份**：定期备份文档，防止数据丢失
- **协作**：在团队协作中，制定统一的 Markdown 规范
## 18. 工具推荐
### 18.1. 编辑器
| 编辑器 | 特点 | 适用平台 |
|--------|------|----------|
| **Visual Studio Code** | 功能强大，插件丰富，支持实时预览 | Windows, macOS, Linux |
| **Typora** | 所见即所得，实时预览，界面简洁 | Windows, macOS, Linux |
| **Sublime Text** | 轻量快速，可扩展性强 | Windows, macOS, Linux |
| **Atom** | 开源免费，可定制性强 | Windows, macOS, Linux |
| **MarkdownPad** | 专为 Markdown 设计，功能丰富 | Windows |
| **MacDown** | 专为 macOS 设计，简洁易用 | macOS |
### 18.2. 在线工具
| 工具 | 特点 | 网址 |
|------|------|------|
| **GitHub Gist** | 在线分享代码和文档 | https://gist.github.com/ |
| **Markdown Live Preview** | 在线实时预览 Markdown | https://markdownlivepreview.com/ |
| **Dillinger** | 在线 Markdown 编辑器 | https://dillinger.io/ |
| **StackEdit** | 在线 Markdown 编辑器，支持云存储 | https://stackedit.io/ |
### 18.3. 转换工具
| 工具 | 特点 | 适用场景 |
|------|------|----------|
| **Pandoc** | 强大的文档转换工具，支持多种格式 | 批量转换文档 |
| **Markdown to PDF** | 将 Markdown 转换为 PDF | 生成电子书、报告 |
| **GitBook** | 基于 Markdown 的文档网站生成工具 | 构建文档网站 |
| **VuePress** | 基于 Vue 的静态站点生成器 | 构建技术文档 |
| **Docusaurus** | Facebook 开源的文档网站生成工具 | 构建大型文档 |
### 18.4. 插件与扩展
| 插件 | 功能 | 适用编辑器 |
|------|------|------------|
| **Markdown All in One** | 提供 Markdown 快捷操作和自动完成 | VS Code |
| **Markdown Preview Enhanced** | 增强的 Markdown 预览功能 | VS Code |
| **GitHub Markdown Preview** | 模拟 GitHub 的 Markdown 渲染 | VS Code |
| **Mermaid** | 支持在 Markdown 中绘制图表 | 多种编辑器 |
| **MathJax** | 支持在 Markdown 中编写数学公式 | 多种编辑器 |
## 19. 总结
### 19.1. Markdown 核心优势
- **简单易用**：语法简洁明了，学习成本低
- **可读性强**：纯文本格式，易于阅读和编辑
- **跨平台兼容**：几乎所有现代工具都支持
- **可扩展性**：支持嵌入 HTML 和各种扩展语法
- **广泛应用**：在 GitHub、博客、文档等场景中广泛使用
### 19.2. 学习建议
1. **掌握基础语法**：先学习 Markdown 的基础语法，如标题、段落、列表等
2. **实践练习**：通过实际编写文档来巩固语法
3. **使用工具**：选择适合自己的 Markdown 编辑器，提高效率
4. **参考规范**：学习常见的 Markdown 规范和最佳实践
5. **持续学习**：关注 Markdown 的新特性和扩展
### 19.3. 最终建议
- **保持一致性**：在文档中保持一致的语法风格
- **注重可读性**：优先考虑文档的可读性，而不是追求复杂的语法
- **版本控制**：使用 Git 等工具管理文档的版本
- **分享与交流**：与他人分享 Markdown 文档，获取反馈
- **持续改进**：不断学习和改进自己的 Markdown 写作技巧
Markdown 是一种简单而强大的标记语言，它不仅可以帮助你创建结构清晰的文档，还可以提高你的写作效率。通过掌握 Markdown，你可以更专注于内容本身，而不是排版和格式问题。
---
## 20. 版本历史
| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 2026-04-05 | 1.0 | 初始创建 | fanquanpp |
| 2026-04-05 | 1.1 | 扩写内容，增加详细的使用场景、工具推荐和扩展语法 | fanquanpp |

Footnotes

  1. 这是一个脚注示例 ↩

知识检测

学习进度

-- 已学文档
--% 知识覆盖率

学习推荐

专注模式