抱歉，您的浏览器无法访问本站

本页面需要浏览器支持（启用）JavaScript


了解详情 >

Markdown 使用指南 - 基础语法

無名
或许有用精华拾取

更新于：2021年7月10日
次浏览

字数：3.3k字

时长：12分钟

本文主要介绍 Markdown 的基础语法，Markdown 扩展语法请参考 这里
本文转载自 链滴社区 ，并且在原文基础上作出了一些修改

总览

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

标题

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

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

标题可选语法

除了使用 ATX 标题外，我们还可以用 Setext 标题：在文本下一行用一个或多个等号 = 表示一级标题，一个或多个短横线 - 表示二级标题。

1
2
3
4
5
一级标题
=======

二级标题
------------

标题最佳实践

  1. 段落之间的 ATX 标题最好使用空行分隔。因为有的 Markdown 引擎不识别缺少前后空行的标题语法。
  2. ATX 标题的井号后 务必加上一个空格。
  3. 尽量不要使用 Setext 语法来写标题，因为 Setext 语法只能写到二级标题。

段落

使用空行分隔文本即可

段落最佳实践

  1. 段落开头不要使用空格或者制表符（\t 即 Tab 键）来缩进，否则可能会被当做代码块渲染。
  2. 中文传统排版上段落开头有着 “空两格” 的习惯，可以使用全角空格 　 或者 HTML 实体 &emsp; 。

折行

如果需要文本折行 <br>，可在文本结尾加上两个或更多的空格然后回车。

折行最佳实践

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

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

加粗和斜体

加粗

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

1
2
把文本 **加粗** 一下
把文本 __加粗__ 一下

把文本 加粗 一下
把文本 加粗 一下

加粗最佳实践

加粗用星号和用下划线的不同之处在于星号用法前后可以不加空格，但下划线必须要加。

1
2
把文本**加粗**一下
把文本__加粗__一下

把文本加粗一下
把文本__加粗__一下

斜体

要使文本斜体，可以使用一个星号 * 或者一个下划线 _ 包裹待斜体的文本。

1
2
这两个字是 *斜体* 着的
这两个字是 _斜体_ 着的

这两个字是 斜体 着的
这两个字是 斜体 着的

强调最佳实践

和加粗类似，星号用法前后可以不加空格，但下划线必须要加。

1
2
这两个字是*斜体*着的
这两个字是_斜体_着的

这两个字是斜体着的
这两个字是_斜体_着的

加粗并斜体

如果你需要加粗的同时使文本斜体，可以使用三个星号 *** 或者三个下划线 ___ 包裹待斜体的文本。

1
同时 ***加粗并强调*** 的示例

同时 加粗并强调 的示例

块引用

要创建块引用 <blockquote> 的话仅需在段落前加上大于号 >。

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

渲染结果

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

块引用内分段

如果需要分段的话需要可以在分段空行前加上一个 >。

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

渲染结果：

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

风雨里追赶， 雾里分不清影踪
天空海阔你与我

嵌套块引用

块引用可以嵌套使用，在段落前添加两个大于号 >> 表示两层嵌套

1
2
3
> 块引用段落
> 
> > 嵌套的块引用段落

渲染结果：

块引用段落

嵌套的块引用段落

块引用包含其他元素

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

1
2
3
4
5
6
> ## 标题是块级元素
> 
> * 列表项一是容器块元素
> * 列表项二也是容器块元素
> 
> **加粗**和*强调*是行级元素

渲染结果：

标题是块级元素

  • 列表项一是容器块元素
  • 列表项二也是容器块元素

加粗 和 强调 是行级元素

列表

列表分为有序列表和无序列表。Markdown 中的列表只能包含列表项元素，列表项和块引用一样，都是容器块。也就是说列表项可以包含其他任意元素

有序列表

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

1
2
1. 列表项一
2) 列表项二

渲染结果：

  1. 列表项一
  2. 列表项二

无序列表

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

1
2
3
- 列表项一
+ 列表项二
* 列表项三

渲染结果：

  • 列表项一
  • 列表项二
  • 列表项三

列表项包含其他元素

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

列表项包含段落

1
2
3
4
5
* 列表项一
* 列表项二第一段
  
  这是第二段
* 列表项三

渲染结果：

  • 列表项一
  • 列表项二第一段这是第二段
  • 列表项三

列表项包含块引用

1
2
3
4
5
* 列表项一
* 列表项二第一段
  
  > 第二段是块引用
* 列表项三

渲染结果：

  • 列表项一
  • 列表项二第一段

    第二段是块引用

  • 列表项三

列表项包含图片

1
2
3
4
* 列表项一
* 列表项二第一段
  ![Logo](https://cdn.jsdelivr.net/gh/syy0322/Picture/2020/09/favicon.webp)
* 列表项三

渲染结果：

  • 列表项一
  • 列表项二第一段

  • 列表项三

代码

代码可以通过两个反引号 `` 包裹

一个 printf() 函数

转义反引号

如果你需要显示反引号，可以用转义符 \ 来对反引号进行转义

1
打个反引号 \`

渲染结果：

打个反引号 `

代码块

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

1
2
3
4
5
6
​```html
<html>
  <head>
  </head>
</html>
​```

分隔线

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

1
2
3
***
---
___

渲染结果：

超链接

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

1
这是我的个人主页 [IMSYY](https://imsyy.top/)

渲染结果：

这是我的个人主页 IMSYY

添加超链接标题

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

1
这是我的个人主页 [IMSYY](https://imsyy.top/ "我的主页")

渲染结果：

这是我的个人主页 IMSYY

URL 和邮件地址

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

1
2
<https://blog.imsyy.top>
<one@imsyy.top>

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

1
2
https://blog.imsyy.top
one@imsyy.top

渲染结果：

https://blog.imsyy.top
one@imsyy.top

超链接格式排版

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

1
2
这是我的个人主页 **[IMSYY](https://imsyy.top)**
欢迎来到我的博客 **[`無名小栈`](https://blog.imsyy.top)**

渲染结果：
这是我的个人主页 IMSYY
欢迎来到我的博客 無名小栈

引用风格的超链接

使用引用风格的超链接可以让 Markdown 原文更容易阅读。引用风格的超链接分为两部分：链接引用和链接定义。

链接引用

链接引用用于在需要插入超链接的地方，它由两组方括号构成，第一组方括号用于指定链接文本，第二组方括号用于指定链接标识，链接标识指向链接定义。

1
2
3
[我的主页][链接]

[链接]: https://imsyy.top

渲染结果：

我的主页

链接引用也可以只由一组方括号构成，这种情况下链接标识将用于链接文本。

1
2
3
[我的主页]

[链接]: https://b3log.org

渲染结果：

我的主页

链接定义

链接定义由三部分构成：

  1. 方括号包裹定义链接标识，后跟冒号 :
  2. URL，可以直接写也可以用尖括号 < > 包裹
  3. 链接标题，这部分是可选的，可以用双引号、单引号或者圆括号包裹
1
2
3
4
5
[我的主页]: https://imsyy.top
[链接标识]: <https://imsyy.top>
[链接标识]: https://imsyy.top "我的主页"
[链接标识]: https://imsyy.top '我的主页'
[链接标识]: https://imsyy.top (我的主页)

链接定义可以放在整个 Markdown 文本的任何位置。有的人习惯将其放于引用所在段落之后，有的人习惯将其放于文末位置

超链接最佳实践

英文内容天然使用空格分隔，所以在使用自动超链接时不存在分隔问题。但中文会存在该问题，比如：

1
欢迎来到我的博客https://blog.imsyy.top

这段内容在很多 Markdown 引擎上会渲染不正确。为了尽量保证兼容性，可以考虑使用空格进行分隔：

1
欢迎来到我的博客 https://blog.imsyy.top

或者使用尖括号 <> 包裹：

1
欢迎来到我的博客<https://blog.imsyy.top>

这样就能得到预期的渲染结果了：

欢迎来到我的博客 https://blog.imsyy.top

图片

使用感叹号 ! 后跟超链接就可以渲染图片了。

1
![Logo](https://cdn.jsdelivr.net/gh/syy0322/Picture/2020/09/favicon.webp)

渲染结果：

超链接嵌套图片

如果你需要图片点击可以跳转超链接，只需要在链接文本部分包含图片即可。

1
[![Logo](https://cdn.jsdelivr.net/gh/syy0322/Picture/2020/09/favicon.webp)](https://imsyy.top)

转义字符

可使用反斜杠 \ 来转义如下字符：

字符 中文名称
\ 反斜杠
` 反引号
* 星号
_ 下划线
{} 花括号
[] 方括号
() 圆括号
# 井号
+ 加号
- 短横线（减号）
. 点
! 感叹号

几乎所有 ASCII 标点符号都可以使用反斜杠进行转义

嵌入 HTML

Markdown 天然支持嵌入 HTML 代码。

1
**Markdown** 和 <em>HTML</em> 混合排版

渲染结果：

Markdown 和 HTML 混合排版

嵌入 HTML 最佳实践

这在需要设置图片大小、字体颜色时会比较有用，但我们并不建议过多使用 HTML 来进行排版，一来是因为这样做实际上并不通用，因为有的 Markdown 引擎因为安全原因会过滤部分标签或者属性；二来是因为这样做太不 Markdown 了！

另外，请勿在 HTML 中嵌入 Markdown，这样并不工作：

1
<p>**粗体**不会生效</p>

总结

使用好空行和空格是 Markdown 排版的关键，很多时候就是因为少了个空行或者空格导致产生了非预期的渲染结果。

随着 CommonMark / GFM 规范日趋完善并逐渐成为业界统一的 Markdown 标准，已经有越来越多的 Markdown 引擎实现了该规范。建议 Markdown 使用者尽量该遵循规范来进行排版，这样才能最大程度地避免细节渲染问题。

发布于：2020年12月2日

Markdown

使用指南

评论区 请大家友善讨论哦