一篇简明扼要的 Markdown 魔法速成教程

Markdown 是一款轻量级的文本标记语言，由约翰·格鲁伯（John Gruber）于 2004 年开发，主要用于在纯文本文档当中添加格式化元素。具有语法简单，易于读写的特点，同时也可以方便的纳入 Git 进行版本控制。其源文件采用 .md 或者 .markdown 扩展名，可以被 Pandoc 等预处理工具渲染为指定 CSS 样式的 HTML 页面。除了使用 VSCode、Sublime 等编辑器进行撰写，还可以采用 Markdown 在线编辑器，或者借用 Markdown 在线表格生成器 辅助生成内容。

笔者日常开发设计工作当中，经常需要使用到 Markdown 来撰写各类技术笔记，以及项目的 README.md 文档。不同于网络上其它琳琅满目的 Markdown 在线教程，这篇文章会在介绍相关语法特性的同时，侧重于体现 Markdown 语法与 HTML 元素之间的映射关系，从而更加清晰的呈现其底层的转换逻辑，便于大家结合自定义的 CSS 样式与 HTML 标签，创造出更加丰富多彩的 Markdown 文本内容。

全体语法速览表

下面表格当中的 Markdown 基本元素，是作者 John Gruber 最初设计的元素，几乎所有的 Markdown 预处理工具都支持它们。

Markdown 基本元素	Markdown 语法
标题（Heading）	# 标题层级 1 ## 标题层级 2 ### 标题层级 3 #### 标题层级 4 ##### 标题层级 5 ###### 标题层级 6
粗体（Bold）	**粗体文本内容**
斜体（Italic）	*斜体文本内容*
引用块（Blockquote）	> 引用的内容
有序列表（Ordered List）	1. 第 1 条有序列表项； 2. 第 2 条有序列表项； 3. 第 3 条有序列表项；
无序列表（Unordered List）	- 这是一条无序列表项； - 这是一条无序列表项； - 这是一条无序列表项；
代码（Code）	`行内代码`
分隔线（Horizontal Rule）	---
链接（Link）	[链接名称](链接地址 "链接标题")
图片（Image）	

而下面表格当中的 Markdown 扩展元素，则是由各种 Markdown 预处理工具自行扩展而来，使用时需要特别注意其兼容性。

Markdown 扩展元素	Markdown 语法
表格（Table）	| 表头 | 表头 | | :--------: | :--------: | | 单元格内容 | 单元格内容 | | 单元格内容 | 单元格内容 |
代码块（Fenced Code Block）	` ` ` json { "URL": "UinIO.com", "name": "电子技术实验室" } ` ` `
☀ 脚注（Footnote）	这里是一个带有脚注的句子。[^1] [^1]: 这里是脚注的内容。
☀ 标题自定义 ID（Heading ID）	### 这是一个标题 {#自定义 ID }
☀ 定义列表（Definition List）	专业术语 : 第 1 条术语定义。 : 第 2 条术语定义。
删除线（Strikethrough）	~~这是一段带有删除线的文字。~~
任务列表（Task List）	- [x] 第 1 个任务项。 - [ ] 第 2 个任务项。 - [ ] 第 3 个任务项。

注意：上述表格当中使用 ☀ 标注的 脚注、标题自定义 ID、定义列表，在大部分 Markdown 预处理工具当中存在有兼容性问题，使用时需要特别注意。

Markdown 标题

Markdown 通过在内容的前面使用 # 号来添加标题，其中 # 的数量代表了标题的层级。例如 3 个 # 号就表示创建了一个三级标题 <h3>。

Markdown 语法	HTML 语句	效果预览
# 标题层级 1	<h1>标题层级 1</h1>	标题层级 1
## 标题层级 2	<h2>标题层级 2</h2>	标题层级 2
### 标题层级 3	<h3>标题层级 3</h3>	标题层级 3
#### 标题层级 4	<h4>标题层级 4</h4>	标题层级 4
##### 标题层级 5	<h5>标题层级 5</h5>	标题层级 5
###### 标题层级 6	<h6>标题层级 6</h6>	标题层级 6

注意：最佳实践是在 # 号与标题之间使用【空格】进行分隔，从而能够规避一些兼容性方面的问题。

Markdown 段落

Markdown 使用一个或者多个的空行来实现段落的效果。

Markdown 语法	HTML 语句	效果预览
这是第 1 个段落。 这是第 2 个段落。 这是第 3 个段落。	<p>这是第 1 个段落。</p> <p>这是第 2 个段落。</p> <p>这是第 3 个段落。</p>	这是第 1 个段落。 这是第 2 个段落。 这是第 3 个段落。

Markdown 换行

Markdown 在内容的末尾添加两个或者多个空格，然后再按下回车键，就可以创建出一个换行效果。

Markdown 语法	HTML 语句	效果预览
这是第 1 行内容。 这是第 2 行内容。 这是第 3 行内容。	<p> 这是第 1 行内容。<br /> 这是第 2 行内容。<br /> 这是第 3 行内容。 </p>	这是第 1 行内容。 这是第 2 行内容。 这是第 3 行内容。

注意：某些 Markdown 编辑器的格式化工具，会自动清除内容末尾的空格，从而导致换行不成功，所以推荐使用段落来实现类似换行的效果。

Markdown 强调

Markdown 通过粗体和斜体来实现强调的效果。其中在内容的前后，分别添加两个星号 ** 或者两条下划线 __，就可以实现粗体的效果。

Markdown 语法	HTML 语句	效果预览
使用星号的**粗体内容**。	使用星号的<strong>粗体内容</strong>。	使用星号的粗体内容。
使用下划线的__粗体内容__。	使用下划线的<strong>粗体内容</strong>。	使用下划线的粗体内容。

除此之外在内容的前后，还可以分别添加一个星号 * 或者一条下划线 _，从而实现出斜体的效果。

Markdown 语法	HTML 语句	效果预览
使用星号的*斜体内容*。	使用星号的<em>斜体内容</em>。	使用星号的斜体内容。
使用下划线的_粗体内容_。	使用下划线的<em>斜体内容</em>。	使用下划线的斜体内容。

如果需要同时运用粗体加上斜体的效果来强调内容，那么可以在该内容前后分别添加三个星号 *** 或者三条下划线 ___，并且保留一个空格。

Markdown 语法	HTML 语句	效果预览
使用星号的***粗体加斜体***内容。	使用星号的<em><strong>粗体加斜体内容</strong></em>。	使用星号的粗体加斜体内容。
使用下划线的___粗体加斜体___内容。	使用下划线的<em><strong>粗体加斜体内容</strong></em>。	使用下划线的 粗体加斜体内容 。

注意：某些 Markdown 编辑器的格式化工具，会自动把 _内容_ 转换为 *内容*、__内容__ 转换为 **内容**、***内容*** 转换为 **_内容_**，所以这里推荐遵循如下规则来使用 Markdown 的强调语法：

1. 粗体 使用 **内容** 语法；
2. 斜体 使用 *内容* 语法；
3. 粗体加斜体 使用 **_内容_** 语法（注意左右两侧需要保留 1 个空格）；

Markdown 引用

Markdown 通过在内容段落的前面添加 > 符号来实现引用效果。

Markdown 语法	HTML 语句	效果预览
> 这里引用了一段内容。	<blockquote> <p>这里引用了一段内容。</p> </blockquote>	这里引用了一段内容。

通过使用一个内容为空的 > 引用，就可以实现对引用内容的换行效果：

Markdown 语法	HTML 语句	效果预览
> 这里是第 1 段引用内容。 > > 这里是第 2 段引用内容。	<blockquote> <p>这里是第 1 段引用内容。</p> <p>这里是第 2 段引用内容。</p> </blockquote>	这里是第 1 段引用内容。 这里是第 2 段引用内容。

通过重复使用 > 内容 还可以实现对于引用内容的嵌套显示：

Markdown 语法	HTML 语句	效果预览
> 这是最外层的引用内容。 >> 这是第 1 层嵌套的引用内容。 >>> 这是第 2 层嵌套的引用内容。	<blockquote> <p>这是最外层的引用内容。</p> <blockquote> <p>这是第 1 层嵌套的引用内容。</p> <blockquote> <p>这是第 2 层嵌套的引用内容。</p> </blockquote> </blockquote> </blockquote>	这是最外层的引用内容。 这是第 1 层嵌套的引用内容。 这是第 2 层嵌套的引用内容。

除此之外，还可以在 Markdown 的引用当中嵌套无序列表和有序列表：

<tr>
  <td>
    

Markdown 语法	HTML 语句	效果预览
> 这是一条引用内容： > - 这是一条无序列表项； > - 这是一条无序列表项；	<blockquote> <p>这是一条引用内容：</p> <ul> <li>这是一条无序列表项；</li> <li>这是一条无序列表项；</li> </ul> </blockquote>	这是一条引用内容： 这是一条无序列表项； 这是一条无序列表项；

1 2 3

> 这是一条引用内容： > 1. 这是第 1 条有序列表项； > 2. 这是第 2 条有序列表项；

</td> <td>

<blockquote>
  <p>这是一条引用内容：</p>
  <ol>
    <li>这是第 1 条有序列表项；</li>
    <li>这是第 2 条有序列表项；</li>
  </ol>
</blockquote>

</td> <td> <blockquote> <p>这是一条引用内容：</p> <ol> <li>这是第 1 条有序列表项；</li> <li>这是第 2 条有序列表项；</li> </ol> </blockquote> </td> </tr>

Markdown 列表

Markdown 可以使用 - 列表项内容（推荐使用）、* 列表项内容、+ 列表项内容 语法来渲染无序列表：

Markdown 语法	HTML 语句	效果预览
- 这是一条无序列表项； - 这是一条无序列表项； - 这是一条无序列表项；	<ul> <li>这是一条无序列表项；</li> <li>这是一条无序列表项；</li> <li>这是一条无序列表项；</li> </ul>	这是一条无序列表项； 这是一条无序列表项； 这是一条无序列表项；

除此之外，Markdown 还可以通过 序数. 列表内容 语法来渲染有序列表：

Markdown 语法	HTML 语句	效果预览
1. 这是第 1 条有序列表项； 2. 这是第 2 条有序列表项； 3. 这是第 3 条有序列表项；	<ol> <li>这是第 1 条有序列表项；</li> <li>这是第 2 条有序列表项；</li> <li>这是第 3 条有序列表项；</li> </ol>	这是第 1 条有序列表项； 这是第 2 条有序列表项； 这是第 3 条有序列表项；

如需需要在列表当中插入其它内容（包括图片、代码块、其它列表、换行、引用），则需要将该内容缩进一个制表符或者四个空格：

Markdown 语法	HTML 语句	效果预览
- 这是一条无序列表项； > 这是一个引用。 - 这是一条无序列表项； - 这是一条无序列表项；	<ul> <li>这是一条无序列表项； <blockquote> <p>这是一个引用。</p> </blockquote> </li> <li>这是一条无序列表项；</li> <li>这是一条无序列表项；</li> </ul>	这是一条无序列表项； 这是一个引用。 </li> <li>这是一条无序列表项；</li> <li>这是一条无序列表项；</li> </ul> </td> </tr>

Markdown 代码

Markdown 使用一个反引号 ` 语法来展示行内的代码片断：

Markdown 语法	HTML 语句	效果预览
`这是一条行内代码片断`	<code>这是一条行内代码片断</code>	这是一条行内代码片断

如果需要在一个行内的代码片断当中，展示反引号内容，则可以将其包裹在两个反引号 `` 当中进行转义。

Markdown 语法	HTML 语句	效果预览
`` 一行内容 `代码片段` 一行内容 ``	<code>一行内容 `代码片段` 一行内容</code>	一行内容 代码片段 一行内容

除此之外，Markdown 支持通过三个反引号 ```（推荐使用）或者波浪号 ~~~ 来展示块级的代码片段：

` ` `
int main(void) {
  printf("Hello UinIO.com!");
}
` ` `

如果在第一个 ``` 或 ~~~ 后面，添加当前代码片断所使用的编程语言名称（例如下面例子使用的 C 语言），则可以启用相应的语法高亮：

` ` ` C
int main(void) {
  printf("Hello UinIO.com!");
}
` ` `

注意：上面代码为了避免错误渲染，在 ` 与 ` 之间添加了额外的空格，实际使用时需要去除掉这些空格。

Markdown 分隔线

Markdown 通过在单独的一行上面，使用三个或者多个星号 ***、破折号 ---、下划线 ___（推荐使用）就可以渲染出分隔线：

Markdown 语法	HTML 语句	效果预览
---	<hr>

Markdown 链接

Markdown 当中可以使用 [链接名称](链接地址 "链接标题") 格式的语法添加一个超级链接：

Markdown 语法	HTML 语句	效果预览
[链接名称](链接地址 "链接标题")	<a href="链接地址" title="链接标题">链接名称</a>	链接名称

注意：链接标题 是鼠标在链接上悬停时显示的信息，链接名称 是链接实际渲染时显示的内容，链接地址 则是需要跳转到的目标 URL 地址。

使用尖括号 <> 语法，可以方便的将 URL 地址或者 E-Mail 地址转换为链接。

Markdown 语法	HTML 语句	效果预览
<http://www.uinio.com> <uinika@outlook.com>	<a href="http://www.uinio.com/">http://www.uinio.com</a> <a href="mailto:uinika@outlook.com">uinika@outlook.com</a>	http://www.uinio.com uinika@outlook.com

Markdown 图片

Markdown 里可以通过 ![图片替代文本](图片地址 "图片标题") 格式语法插入一张图片：

Markdown 语法	HTML 语句	效果预览
	<img src="./Markdown/logo.png" alt="Logo" title="Markdown">

注意：图片替代文本 是图片资源缺失时显示的信息，图片地址 是图片的 URL 地址，图片标题 则是鼠标悬停时显示的信息。

如果需要为图片添加一个 URL 链接，则只需要将上述的图片语法嵌入至链接语法内部即可：

Markdown 语法	HTML 语句	效果预览
[](http://www.uinio.com)	<a href="http://www.uinio.com/"><img src="./Markdown/logo.png" alt="Logo" title="Markdown"></a>

Markdown 表格

Markdown 当中可以通过使用连字符 --- 和管道符 | 来构建表格。

Markdown 语法	HTML 语句	效果预览
| 表头 | 表头 | | ------ | ------ | | 单元格 | 单元格 | | 单元格 | 单元格 |	<table> <thead> <tr> <th>表头</th> <th>表头</th> </tr> </thead> <tbody> <tr> <td>单元格</td> <td>单元格</td> </tr> <tr> <td>单元格</td> <td>单元格</td> </tr> </tbody> </table>	表头 表头 单元格 单元格 单元格 单元格

通过向 Markdown 表格当中连字符的左右两侧添加 : 冒号，就可以控制表格当中文本的左、中心、右对齐（实质是向表格的 <th>、<td> 标签添加了 align="left/center/right" 属性）。

Markdown 语法	HTML 语句	效果预览
| 表头 | 表头 | | :----: | :----: | | 单元格 | 单元格 | | 单元格 | 单元格 |	<table> <thead> <tr> <th align="center">表头</th> <th align="center">表头</th> </tr> </thead> <tbody> <tr> <td align="center">单元格</td> <td align="center">单元格</td> </tr> <tr> <td align="center">单元格</td> <td align="center">单元格</td> </tr> </tbody> </table>	表头 表头 单元格 单元格 单元格 单元格

注意：如果需要在表格当中显示管道符 |，为了避免语法冲突，则需要改为直接使用 HTML 实体 |。

Markdown 转义字符

Markdown 当中可以使用反斜杠 \ 来转义下面列表当中的这些字符。

\	`	*	_	#
{ }	[ ]	( )	+	-
.	!	|

注意：对于 Markdown 当中出现的 < 和 & 两个特殊符号，就需要使用其对应的 HTML 实体形式 < 和 & 才能够正常显示。

Markdown 任务列表

Markdown 可以基于减号 -、方括号 [ ]、字母 x 创建出一个可进行勾选的任务列表。

Markdown 语法	HTML 语句	效果预览
- [x] 今天的第 1 个任务项。 - [ ] 今天的第 2 个任务项。 - [ ] 今天的第 3 个任务项。	<ul> <li> <input disabled="" type="checkbox" checked=""> 今天的第 1 个任务项 </li> <li> <input disabled="" type="checkbox"> 今天的第 2 个任务项。 </li> <li> <input disabled="" type="checkbox"> 今天的第 3 个任务项。 </li> </ul>	今天的第 1 个任务项 今天的第 2 个任务项。 今天的第 3 个任务项。

Markdown 删除线

Markdown 可以通过向指定内容的左右两侧，分别添加两个波浪号 ~~，从而在这些内容上面显示一条删除线：

Markdown 语法	HTML 语句	效果预览
~~这是需要删除的内容~~，而这是正常显示的内容。	<p> <del>这是需要删除的内容</del>，而这是正常显示的内容。 </p>	这是需要删除的内容 ，而这是正常显示的内容。