Markdown 使用指南 - 基础语法

总览
几乎所有的 Markdown 引擎都支持 Markdown 发明者 John Gruber 所设计的基本语法。但不同的 Markdown 处理引擎在细节表现方面略有不同，下面会逐一介绍。

标题
要创建标题的话只需使用井号 # 开头，井号的数量对应标题的级别。比如如果你想要创建一个 <h3> 则可以通过用三个 # 开头：### 三级标题 。使用井号的标题语法在 CommonMark 规范中称之为“ATX 标题”。

Markdown
HTML
渲染结果
# 一级标题
<h1>一级标题</h1>
一级标题
## 二级标题
<h2>二级标题</h2>
二级标题
### 三级标题
<h3>三级标题</h3>
三级标题
#### 四级标题
<h4>四级标题</h4>
四级标题
###### 五级标题
<h5>五级标题</h5>
五级标题
####### 六级标题
<h6>六级标题</h6>
六级标题
标题可选语法
除了使用 ATX 标题外，我们还可以用 Setext 标题：在文本下一行用一个或多个等号 = 表示一级标题，一个或多个短横线 - 表示二级标题。

Markdown
HTML
渲染结果
一级标题
======
<h1>一级标题</h1>
一级标题
二级标题
------------
<h2>二级标题</h2>
二级标题
标题最佳实践
段落之间的 ATX 标题最好使用空行分隔。因为有的 Markdown 引擎不识别缺少前后空行的标题语法。

✅ 稳妥
❌ 不稳妥
这是一个段落。

# 一级标题

另一个段落。
这是一个段落。
# 一级标题
另一个段落
ATX 标题的井号后务必加上一个空格

✅ 稳妥
❌ 不稳妥
# 一级标题
#一级标题
尽量不要使用 Setext 语法来写标题，因为 Setext 语法只能写到二级标题
段落
使用空行分隔文本即可。

Markdown
HTML
渲染结果
我很喜欢使用 Markdown。

我将使用 Markdown 来排版我所有的文档。
<p>我很喜欢使用 Markdown。
<p>我将使用 Markdown 来排版我所有的文档。</p>
我很喜欢使用 Markdown。

我将使用 Markdown 来排版我所有的文档。
段落最佳实践
段落开头不要使用空格或者制表符（\t 即 Tab 键）来缩进，否则可能会被当做代码块渲染。

✅ 稳妥
❌ 不稳妥
开头不要缩进。

像这样保持左对齐就好。
开头缩进可能会被渲染为代码块。
中文传统排版上段落开头有着“空两格”的习惯，可以使用全角空格 　 或者 HTML 实体 &emsp。科技领域的文章排版建议不要空两格，段落居左对齐较好
折行
如果需要文本折行 <br>，可在文本结尾加上两个或更多的空格然后回车。

Markdown
HTML
渲染结果
这是第一行。
这是第二行。
<p>这是第一行。<br>这是第二行。</p>
这是第一行。
这是第二行。
折行最佳实践
目前大部分 Markdown 引擎会自动将换行符 \n 转换为 <br>，即软换行转硬换行。所以结尾用两个或更多空格的写法虽然稳妥，但是可能也会造成一些小问题：结尾空格在一些编辑器中并不可视；不小心按到或者习惯性按到会造成错误排版。介于这些小问题，可能用 <br> 来折行是最稳妥的做法，但这又不太优雅。另外，在 CommonMark 规范中可以在文本结尾使用反斜杠 \ 来折行，但我也不太推荐这种写法。

综上，我的建议是不要使用结尾空格、\ 或者 <br>，因为现在几乎所有的 Markdown 引擎基本都已经支持软换行转硬换行了。

加粗和强调
加粗对应粗体，强调对应斜体。

加粗
要加粗文本，可以使用两个星号 ** 或者两个下划线 __ 包裹待加粗的文本。

Markdown
HTML
渲染结果
把文本**加粗**一下
把文本<strong>加粗</strong>一下
把文本加粗一下
把文本 __加粗__ 一下
把文本 <strong>加粗 </strong>一下
把文本 加粗 一下
加粗最佳实践
加粗用星号和用下划线的不同之处在于星号用法前后可以不加空格，但下划线必须要加。

✅ 稳妥
❌ 不稳妥
星号**加粗**无需空格
没有空格下划线__加粗__无效
强调
要强调文本，可以使用一个星号 * 或者一个下划线 _ 包裹待强调的文本。

Markdown
HTML
渲染结果
把文本*强调*一下
把文本<em>强调</em>一下
把文本强调一下
把文本 _强调_ 一下
把文本 <em>强调</em> 一下
把文本 强调 一下
强调最佳实践
和加粗类似，星号用法前后可以不加空格，但下划线必须要加。

✅ 稳妥
❌ 不稳妥
星号*强调*无需空格
没有空格下划线_强调_无效
加粗并强调
如果你需要加粗的同时强调文本，可以使用三个星号 *** 或者三个下划线 ___ 包裹待强调的文本。

Markdown
HTML
渲染结果
同时 加粗并强调 的示例
同时 <strong><em>加粗并强调</em></strong> 的示例
同时 加粗并强调 的示例
同时 加粗并强调 的示例
同时 <strong><em>加粗并强调</em></strong> 的示例
同时 加粗并强调 的示例
同时 加粗并强调 的示例
同时 <strong><em>加粗并强调</em></strong> 的示例
同时 加粗并强调 的示例
同时 加粗并强调 的示例
同时 <strong><em>加粗并强调</em></strong> 的示例
同时 加粗并强调 的示例
星号可以不用加空格
星号<strong><em>可以不用</em></strong>加空格
星号可以不用加空格
块引用
要创建块引用 <blockquote> 的话仅需在段落前加上大于号 >。

 
> 原谅我这一生不羁放纵爱自由，也会怕有一天会跌倒
> 背弃了理想 ，谁人都可以
> 哪会怕有一天只你共我

渲染结果

原谅我这一生不羁放纵爱自由，也会怕有一天会跌倒
背弃了理想 ，谁人都可以
哪会怕有一天只你共我
块引用内分段
如果需要分段的话需要可以在分段空行前加上一个 >。

 
> 今天我， 寒夜里看雪飘过
> 怀着冷却了的心窝漂远方
>
> 风雨里追赶， 雾里分不清影踪
> 天空海阔你与我

渲染结果：

今天我， 寒夜里看雪飘过
怀着冷却了的心窝漂远方

风雨里追赶， 雾里分不清影踪
天空海阔你与我
嵌套块引用
块引用可以嵌套使用，在段落前添加两个大于号 >> 表示两层嵌套。

 
> 块引用段落
>
>> 嵌套的块引用段落

块引用包含其他元素
块引用能够包含其他大部分语法元素。CommonMark 规范将块引用定义为容器块，容器块可以包含任意块级元素和行级元素，也就是说块引用可以包含其他任意元素。

 
> ### 标题是叶子块元素
>
> * 列表项一是容器块元素
> * 列表项二也是容器块元素
>
> **加粗**和*强调*是行级元素。

渲染结果：

标题是叶子块元素
列表项一是容器块元素
列表项二也是容器块元素
加粗和强调是行级元素。
列表
列表分为有序列表和无序列表。Markdown 中的列表只能包含列表项元素，列表项和块引用一样，都是容器块。也就是说列表项可以包含其他任意元素。

有序列表
有序列表可以通过阿拉伯数字后跟 . 或者 ) 来创建，数字不必递增连续。

Markdown
HTML
渲染结果
1. 列表项一
2. 列表项二

<ol><li>列表项一</li><li>列表项二</li></ol>
列表项一
列表项二
1. 列表项一
1. 列表项二

<ol><li>列表项一</li><li>列表项二</li></ol>
列表项一
列表项二
1. 列表项一
3. 列表项二

<ol><li>列表项一</li><li>列表项二</li></ol>
列表项一
列表项二
无序列表
无序列表可以通过短横线 -、星号 * 或者加号 + 来开头，后面需要跟一个空格来分隔文本内容。

Markdown
HTML
渲染结果
- 列表项一
- 列表项二

<ul><li>列表项一</li><li>列表项二</li></ul>
列表项一
列表项二
* 列表项一
* 列表项二

<ul><li>列表项一</li><li>列表项二</li></ul>
列表项一
列表项二
+ 列表项一
+ 列表项二

<ul><li>列表项一</li><li>列表项二</li></ul>
列表项一
列表项二
列表项包含其他元素
列表项可以包含其他任意元素，比如段落、块引用、代码块、图片等。使用要点是待包含元素的起始字符要和列表项起始内容“对齐”。

列表项包含段落
 
* 列表项一
* 列表项二第一段

这是第二段
* 列表项三

渲染结果：

列表项一
列表项二第一段

这是第二段
列表项三
列表项包含块引用
 
* 列表项一
* 列表项二第一段

> 第二段是块引用
* 列表项三

渲染结果：

列表项一
列表项二第一段第二段是块引用
列表项三
列表项包含代码块
 
* 列表项一
* 列表项二第一段

```
这里是代码块
echo 你好，世界！
```
* 列表项三

渲染结果：

列表项一
列表项二第一段 
这里是代码块
echo 你好，世界！

列表项三
列表项包含图片
 
* 列表项一
* 列表项二第一段

* 列表项三

渲染结果：

列表项一
列表项二第一段

列表项三
代码
代码可以通过反引号 ``` 包裹。

Markdown
HTML
渲染结果
列出文件命令是 `ls`
列出文件命令是 <code>ls</code>
列出文件命令是 ls
转义反引号
如果你需要显示反引号，可以用转义符 \ 来对反引号进行转义。

Markdown
HTML
渲染结果
打个反引号 `
打个反引号 `
打个反引号 `
代码块
代码块可以使用四个空格缩进或者制表符 \t 缩进。

 
<html>
<head>
</head>
</html>

渲染结果：

 
<html>
<head>
</head>
</html>

推荐使用围栏代码块语法来排版代码块，即使用 ``` 来包裹代码块，并且指定语法高亮语言：

 
```html
<html>
<head>
</head>
</html>
```

分隔线
通过大于等于三个星号 ***、短横线 --- 或者下划线 ___ 来创建分隔线。

 
***
---
___

渲染结果：

超链接
通过 [链接文本](URL) 来创建超链接。

 
我们来自小众开源社区 [B3log](https://b3log.org)。

渲染结果：

我们来自小众开源社区 B3log。

添加超链接标题
链接标题是可选的，在圆括号中的 URL 后用双引号包裹。鼠标移到超链接上会浮出显示标题内容。

 
我们来自小众开源社区 [B3log](https://b3log.org "B3log 开源")。

渲染结果：

我们来自小众开源社区 B3log。

URL 和邮件地址
如果要直接显示 URL 或者邮件地址，可以通过 < 和 > 来包裹 URL 或者邮件地址。

 
<https://b3log.org>

<os@b3log.org>

大部分 Markdown 引擎也支持自动转换，这样可以省去 <>：

 
https://b3log.org

os@b3log.org

超链接格式排版
超链接可以和加粗强调、代码等元素结构一同使用。

 
我们来自小众开源社区 **[B3log](https://b3log.org)**。
我们来自小众开源社区 [`B3log`](https://b3log.org)。

渲染结果：

 

作者：88250
链接：https://hacpai.com/article/1583129520165
来源：黑客派
协议：CC BY-SA 4.0 https://creativecommons.org/licenses/by-sa/4.0/