Markdown 语法速查
Markdown 最初没有严格的规范，不同渲染器对同一段文本的处理常常不一致。现在通用的基础是 CommonMark 规范，GitHub 在它之上扩展出 GFM（GitHub Flavored Markdown），增加了表格、任务列表、删除线、自动链接等语法。这篇按这两份规范整理常用语法，并标出容易写错的细节，方便写文档时查阅。
每一项先给出源码，必要时给出渲染效果。标注“GFM”的语法不属于 CommonMark，在只支持 CommonMark 的渲染器里可能不生效。
ATX 风格：行首 1–6 个 #，后面必须跟一个空格。
# 一级标题## 二级标题### 三级标题#### 四级标题##### 五级标题###### 六级标题另一种 Setext 风格只支持一、二级标题，在文字下一行写 = 或 -：
一级标题========
二级标题--------注意事项：
#标题（没有空格）在 CommonMark 中不会被识别为标题，会原样输出。- 一篇文档通常只有一个一级标题。很多文档站点（包括本站）用页面元数据里的标题渲染一级标题，正文从二级标题开始。
- 标题层级不要跳级，比如从
##直接跳到####，会影响目录生成和可访问性。
段落之间用空行分隔。段落内部的单个换行在渲染时会变成空格，不会换行：
这是第一行这一行会和上一行连在一起显示。
空一行之后是新段落。需要在段落内强制换行（生成 <br>），有两种写法：
行尾加两个空格··下一行（·代表空格）
行尾加反斜杠\下一行行尾空格肉眼看不见，也容易被编辑器的“删除行尾空格”功能清掉，推荐用反斜杠。
*斜体* 或 _斜体_**粗体** 或 __粗体__***粗斜体***~~删除线~~（GFM）效果：斜体、粗体、粗斜体、删除线。
注意事项：
- 下划线在单词内部不会触发强调，
snake_case_name会原样显示；星号可以，un*frigging*believable中间部分会变成斜体。所以给单词中间的一部分加强调时用星号。 - 强调标记与内容之间不能有空格，
** 粗体 **不会生效。 - 中文与强调标记相邻时，部分渲染器对
**两侧紧贴标点的情况处理不一致，遇到不生效时，可以在标记外侧加空格，或调整标点位置。
用 -、* 或 + 开头，后面跟空格。同一个列表里保持使用同一种符号，混用会被拆成多个列表。
- 苹果- 香蕉 - 嵌套项要缩进到父项内容的起始位置 - 这里是两个空格- 橙子数字加 . 或 )，后面跟空格。渲染结果只取第一个数字作为起始编号，后面的数字会被忽略：
1. 第一步1. 第二步1. 第三步
3. 从 3 开始编号4. 接着是 4全部写成 1. 的好处是插入、删除条目时不用重新编号。
列表中的段落和代码块
Section titled “列表中的段落和代码块”列表项内的段落、代码块要缩进到与该项内容起始位置对齐。1. 占三个字符，所以后续内容缩进三个空格：
1. 安装依赖：
```bash npm install ```
2. 启动开发服务器。缩进不够时，代码块会跑出列表，后面的编号也会重新从 1 开始。
任务列表（GFM）
Section titled “任务列表（GFM）”- [x] 完成需求评审- [ ] 编写单元测试- [ ] 提交合并请求效果：
- 完成需求评审
- 编写单元测试
- 提交合并请求
方括号里是一个空格（未完成）或 x（已完成）。在 GitHub 的 issue 和合并请求描述中可以直接点击勾选；在普通网页中只是静态显示。
[链接文字](https://example.com)[带标题的链接](https://example.com "鼠标悬停时显示")[站内相对链接](./other-page.md)[跳转到本页的某个标题](#表格)锚点链接中的 # 后面是标题生成的 id。不同平台生成 id 的规则不同（大小写、空格、中文的处理），写之前最好在渲染结果中确认一下。
链接多、地址长时，可以把地址集中写在文末，正文更易读：
详细说明见 [官方文档][docs] 和 [规范][spec]。
[docs]: https://example.com/docs[spec]: https://spec.commonmark.org/<https://example.com><user@example.com>https://example.com（GFM：不加尖括号也会自动识别为链接）在链接语法前加 !：
方括号里的替代文字（alt）在图片加载失败时显示，也会被读屏软件读出，应当写清图片内容。
Markdown 语法本身不能指定图片尺寸，需要控制宽高时使用 HTML：
<img src="./images/architecture.png" alt="系统架构图" width="480" />给图片加链接（点击图片跳转）：
[](https://example.com)> 这是一段引用。> 同一段引用的第二行。>> 引用中的第二个段落。>> > 嵌套引用，再加一个 `>`。效果：
这是一段引用。 同一段引用的第二行。
引用中的第二个段落。
嵌套引用，再加一个
>。
引用内部可以使用列表、代码块等其他语法。两段引用之间如果没有空行隔开，会被合并成同一段引用。
运行 `npm install` 安装依赖。代码本身包含反引号时，用更多的反引号包裹，并在内侧加空格：
`` 用 `code` 表示行内代码 ``用三个反引号（或三个波浪线 ~~~）包裹，开头写上语言名称以启用语法高亮：
```jsconst sum = (a, b) => a + b;```注意事项：
- 语言名称不属于规范强制的内容，具体支持哪些语言取决于渲染器使用的高亮库。常用的有
js、ts、jsx、json、css、html、bash、markdown、diff。 - 要在代码块中展示包含三个反引号的内容，外层改用四个反引号，或者改用
~~~。本文中展示代码块写法的例子都是这样做的。 - CommonMark 也支持用 4 个空格缩进表示代码块，但它无法标注语言，并且容易和列表缩进混淆，建议统一使用反引号围栏。
表格（GFM）
Section titled “表格（GFM）”| 名称 | 类型 | 说明 || :--- | :---: | ---: || id | number | 左对齐、居中、右对齐 || name | string | 由分隔行的冒号决定 |效果：
| 名称 | 类型 | 说明 |
|---|---|---|
| id | number | 左对齐、居中、右对齐 |
| name | string | 由分隔行的冒号决定 |
规则：
- 第二行是分隔行，每列至少一个
-。冒号控制对齐：:---左对齐（默认），:---:居中，---:右对齐。 - 首尾的
|可以省略，但写上更清楚。各列不需要对齐，对齐只是为了源码好看。 - 单元格内容里有
|时要写成\|。 - 单元格内不能直接换行，也不能放列表、代码块等块级内容；需要换行时可以写
<br>（前提是渲染器允许内嵌 HTML）。
单独一行写三个或以上的 -、* 或 _：
---***___注意：--- 如果紧跟在一行文字下面，会把那行文字变成二级标题（Setext 风格）。分隔线上方应留一个空行。
在有特殊含义的字符前加反斜杠 \，让它按普通字符显示：
\*不是斜体\*1986\. 这不是有序列表\# 这不是标题可以转义的字符都是 ASCII 标点，常用的有：
\ ` * _ { } [ ] < > ( ) # + - . ! |代码（行内代码和代码块）内部的内容不需要转义，会原样显示。
内嵌 HTML
Section titled “内嵌 HTML”Markdown 中可以直接写 HTML，用来实现 Markdown 本身不支持的效果，例如折叠内容：
<details><summary>点击展开</summary>
这里的内容默认折叠。HTML 块与 Markdown 内容之间要留空行，否则其中的 Markdown 语法可能不会被解析。
</details>其他常见用途：<kbd>Ctrl</kbd> 表示按键，<sup> / <sub> 表示上下标，<img> 控制图片尺寸。
注意事项：
- 是否允许内嵌 HTML 由渲染器和平台决定。出于安全考虑，很多平台会过滤 HTML：GFM 规范会禁用
<script>、<style>、<iframe>、<textarea>、<title>等标签，GitHub 还会去掉style属性和事件属性。 - 在 HTML 块内部，Markdown 语法通常不会被解析，除非 HTML 标签与 Markdown 内容之间隔着空行（如上例）。
Markdown 由 John Gruber 设计[^1]，CommonMark 对它做了规范化[^spec]。
[^1]: 发布于 2004 年。[^spec]: 详见 https://spec.commonmark.org/渲染后，正文中的 [^1] 显示为上标编号，脚注内容统一列在文档末尾，并带有返回正文的链接。脚注的标识可以是数字或单词，最终显示的编号按出现顺序自动生成。
不同渲染器之间的差异
Section titled “不同渲染器之间的差异”同一份 Markdown 在不同地方显示效果不同，通常是因为：
- 规范不同：只支持 CommonMark 的渲染器不认识表格、任务列表、删除线。
- 扩展不同：数学公式（
$...$）、流程图（如 Mermaid 代码块）、提示块（如> [!NOTE]）、目录标记（[TOC]）都是各平台的扩展，没有统一标准。例如 GitHub 支持在mermaid代码块中画图，但在其他平台上它可能只显示为普通代码块。 - HTML 过滤策略不同：见上一节。
写需要在多个平台显示的文档时，尽量只用 CommonMark 加 GFM 的语法；用到扩展语法时，确认目标平台支持。
- 以 CommonMark 为基础，GFM 增加了表格、任务列表、删除线和自动链接；脚注、数学公式、流程图属于平台扩展。
- 标题的
#后要有空格；段落用空行分隔，段内强制换行推荐用行尾反斜杠。 - 列表嵌套和列表中的代码块要缩进到父项内容的起始位置；有序列表只有第一个数字决定起始编号。
- 代码块标注语言；展示含三个反引号的内容时外层用四个反引号。
- 表格靠分隔行的冒号控制对齐，单元格中的
|要转义。 - 内嵌 HTML 能补足 Markdown 的不足，但是否生效取决于平台的过滤策略。