【总结】- markdown 的使用 & 常用语法

温馨提示

• 前面的内容都是在介绍 markdown，想查看用法直接跳转 Markdown 的常见语法

什么是 Markdown？

概述：

Markdown 是一种轻量级标记语言（类似 HTML），它允许人们使用易读易写的纯文本格式编写文档。Markdown 由 John Gruber 于 2004 年创建，如今已成为世界上最受欢迎的标记语言之一。（e.g 一个项目中的说明文件 README.md, 模块或者软件包的白皮书 xxx.md）

Markdown文件的后缀名便是".md", 比如：README.md``desc.md。。。

为什么要使用 Markdown ？

1. 首先，Markdown 专注于文字内容；
2. Markdown 采用纯文本，易读易写，可以方便地纳入版本控制；
3. Markdown 语言语法简单，没有什么学习成本，能轻松在码字的同时做出美观大方的排版。
4. Markdown 可读性强且不显眼，因此即使 Markdown 文件中的文本未经过渲染也易于阅读。
5. Markdown 无处不在。StackOverflow、CSDN、掘金、简书、GitBook、有道云笔记、V2EX、光谷社区等。主流的代码托管平台，如 GitHub、GitLab、BitBucket、Coding、Gitee 等等，都支持 Markdown 语法，很多开源项目的 README、开发文档、帮助文档、Wiki 等都用 Markdown 写作。

如何使用 Markdown ？

1. 官方文档提供的 markdown 在线编辑链接

打开 Markdown 在线编辑文档链接 即可访问。（这种方式是最方便的，但是要建立在您的 PC 网络环境良好的情况下）

2. 使用 IDE 进行离线编辑

现在有很多的 IDE 都可以支持 markdown 文档（*.md 文件），比如：

• 前端：VSCode，Sublime, WebStorm ...
• 服务端：JIdea，Goland，PhpStorm ...

以VSCode 为例，直接打开一个 *.md文件实时编辑查看即可：

Markdown 的常用语法：

参考表如下：

标题（Heading）

基本语法：

Markdown 创建标题是在文本的前面添加 # ，添加 # 数目表示标题的级别

（类比 HTML的六个级别的标题：<h2>、<h2>、<h3>、<h4>、<h5>、<h6>）

Markdown语法	HTML	预览效果
# 一级标题	# 一级标题	# 一级标题
## 二级标题	## 二级标题	## 二级标题
### 三级标题	### 三级标题	### 三级标题
#### 四级标题	#### 四级标题	#### 四级标题
##### 五级标题	##### 五级标题	##### 五级标题
###### 六级标题	###### 六级标题	###### 六级标题

高级语法：

可以在标题的下方，文本的上方添加一定数量的 ==== 或 ----分表表示 一级标题 和 二级标题

Markdown语法	HTML	预览效果
一级标题 ===============	# 一级标题	# 一级标题
二级标题 ---------------	## 二级标题	## 二级标题

建议用法

不同的 Markdown 应用程序处理 # 和标题之间的空格方式并不一致。为了兼容考虑，请用一个空格在 # 和标题之间进行分隔。

✅ 推荐做法	❌ 不推荐做法
# 我是标题	#我是标题

粗体（Bold）

基本用法

在 Markdown 中，可以使用 **需要加粗的内容** 或者 __需要加粗的内容__ 来加粗字体

Markdown 语法	HTML	预览效果
I just love bold text.	I just love bold text.	I just love bold text.
I just love bold text.	I just love bold text.	I just love bold text.
Loveisbold	Loveisbold	Loveisbold

建议用法

建议使用 **需要加粗的内容** 而不是 __需要加粗的内容__ 语法

✅ 推荐做法	❌ 不推荐做法
**需要加粗的内容**	__需要加粗的内容__

斜体（Italic）

在 Markdown 中，可以使用 *需要斜体显示的内容* 或者 _需要斜体显示的内容_ 来将字体变为斜体

Markdown 语法	HTML	预览效果
普通内容需要斜体显示的内容.	普通内容 需要斜体显示的内容.	普通内容要斜体显示的内容
普通内容_需要斜体显示的内容_.	普通内容 需要斜体显示的内容.	普通内容要斜体显示的内容
Acatmeow	Acatmeow	Acatmeow

建议用法

官方推荐使用*需要斜体显示的内容* 而不是 _需要斜体显示的内容_

✅ 推荐做法	❌ 不推荐做法
*需要斜体显示的内容*	_需要斜体显示的内容_

引用块（Blockquote）

基本用法：

要创建块引用，请在段落前添加一个 > 符号。

> 此处作为引用！！！

渲染效果如下所示：

多个段落的块引用

块引用可以包含多个段落。为段落之间的空白行添加一个 > 符号。

> 闭门造车，出门合辙
>
> 酒肉穿肠过，佛祖心中留。世人若学我，必堕入魔道。

渲染效果如下图所示：

嵌套块使用

块引用可以嵌套。在要嵌套的段落前添加一个 >> 符号。

> 鲁迅先生曾经说过:
>
>> "我从来没有说过这句话"

渲染效果如下图所示：

带有其它元素的块引用

块引用可以包含其他 Markdown 格式的元素。并非所有元素都可以使用，你需要进行实验以查看哪些元素有效。

> #### 注意
>
> - 段落一
> - 段落二
>
>  *我很斜* & **我很粗**

渲染效果如下图所示：

有序列表（Ordered List）

基本用法：

有序列表使用 num. xxx来进行编写，并且需要遵循：

1. 若要创建有序列表，请添加带有数字后跟句号的行项。
2. 这些数字不必按数字顺序排列，但列表应该从数字1开始。（官方推荐的做法）

使用建议：

Markdown 中普通的文档标记和其他一些轻量级标记语言允许您使用圆括号()作为分隔符(例如，1)第一项)，但并非所有Markdown应用程序都支持这一点！

因此从兼容性的角度来看，这不是一个很好的选择。为了兼容性，只使用.。

✅ 推荐做法	❌ 不推荐做法
1. 第一项 2. 第二项	1) 第一项 2) 第二项

无序列表（Unordered List）

基本用法：

若要创建无序列表，请在行项目前面添加破折号(-)、星号(*)或加号(+)。缩进一个或多个项以创建嵌套列表。

Markdown 语法	HTML	预览效果
- 第1项- 第2项- 第3项- 第4项	* 第1项 * 第2项 * 第3项 * 第4项
* 第1项* 第2项* 第3项* 第4项	* 第1项 * 第2项 * 第3项 * 第4项
+ 第1项+ 第2项+ 第3项+ 第4项	* 第1项 * 第2项 * 第3项 * 第4项
- 第1项- 第2项- 第3项- 3.1- 3.2- 3.3- 第4项	* 第1项 * 第2项 * 第3项 * 3.1 * 3.2 * 3.3 * 第4项

使用建议：

Markdown 的语法不支持在同一个无序列表里面使用不同的无序符号（同一个列表里面有 +、-、* 中的任意两个）。如果是同一个无需列表，只能使用同一个无序符号！

✅ 正确做法	❌ 错误做法
- 第1项- 第2项- 第3项- 第4项	+ 第1项* 第2项- 第3项+ 第4项

代码（Code）

基本用法：

Markdown 中使用单行代码要将单词或短语表示为代码，请将其包裹在反引号 (`) 中。

Markdown语法	HTML	预览效果
At the command prompt, type nano.	At the command prompt, type nano.	At the command prompt, type nano.

转义反引号：

如果你要表示为代码的单词或短语中包含一个或多个反引号，则可以通过将单词或短语包裹在双反引号(``)中。

Markdown语法	HTML	预览效果
Use `code` in your Markdown file.	Use ``code`` in your Markdown file.	Use `code` in your Markdown file.

官方建议

要创建不用缩进的代码块，请使用：多行代码快

分隔线（Horizontal Rule）

基本使用：

分割线的用法十分简单：要创建分隔线，请在单独一行上使用三个或多个星号 (***)、破折号 (---) 或下划线 (___) ，并且不能包含其他内容。

***

---

_________________

以上三个分隔线的渲染效果看起来都是一样的

官方建议：

为了兼容性，请在分隔线的前后均添加空白行。

✅ 推荐做法	❌ 不推荐做法
Try to put a blank line before... --- ...and after a horizontal rule.	Without blank lines, this would be a heading. --- Don't do this!

链接（Link）

基本使用：

链接文本放在中括号内，链接地址放在后面的括号中，链接title可选。

语法描述：

超链接 Markdown 语法代码：[超链接显示名](超链接地址 "超链接title")

对应的HTML代码：<a href="超链接地址" title="超链接title">超链接显示名</a>

基本使用：

[百度一下](https://www.baidu.com "Baidu")

网址和Email地址:

使用尖括号可以很方便地把URL或者 email 地址变成可点击的链接。

<https://markdown.com.cn>
<fake@example.com>

渲染效果如下：

markdown.com.cn
fake@example.com

带格式化的链接：

强调链接, 在链接语法前后增加星号。 要将链接表示为代码，请在方括号中添加反引号。

I love supporting the **[EFF](https://eff.org)**.
This is the *[Markdown Guide](https://www.markdownguide.org)*.
See the section on [`code`](#code).

渲染效果如下：

I love supporting the EFF.

This is the Markdown Guide.

See the section on code.

带[索引]的链接：

带[索引]的链接是一种特殊的链接，它使URL在Markdown中更易于显示和阅读。参考样式链接分为两部分：与文本保持内联的部分以及存储在文件中其他位置的部分，以使文本易于阅读。

链接的第一部分格式

引用类型的链接的第一部分使用两组括号进行格式设置。第一组方括号包围应显示为链接的文本。第二组括号显示了一个标签，该标签用于指向您存储在文档其他位置的链接。

尽管不是必需的，可以在第一组和第二组括号之间包含一个空格。第二组括号中的标签不区分大小写，可以包含字母，数字，空格或标点符号。

以下示例格式对于链接的第一部分效果相同：

• hobbit-hole\]\[1

• hobbit-hole\] \[1

链接的第二部分格式

引用类型链接的第二部分使用以下属性设置格式：

1. 放在括号中的标签，其后紧跟一个冒号和至少一个空格（例如[label]:）。
2. 链接的URL，可以选择将其括在尖括号中。
3. 链接的可选标题，可以将其括在双引号，单引号或括号中。

以下示例格式对于链接的第二部分效果相同：

• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Hobbit lifestyles)
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Hobbit lifestyles"
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Hobbit lifestyles)

可以将链接的第二部分放在Markdown文档中的任何位置。有些人将它们放在出现的段落之后，有些人则将它们放在文档的末尾（例如尾注或脚注）。

图片（Image）

基本使用：

要添加图像，请使用感叹号 (!), 然后在方括号增加替代文本，图片链接放在圆括号里，括号里的链接后可以增加一个可选的图片标题文本。

插入图片 Markdown 语法代码：![图片alt](图片链接 "图片title")。

对应的 HTML 代码：<img src="图片链接" alt="图片alt" title="图片title" />

![这是一张图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/314896eb497842a1966d68d8cf7e30a9~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=910&h=682&s=1627253&e=png&b=dba772 "Magic Gardens")

渲染效果如下：

给链接添加图片：

链接图片

给图片增加链接，请将图像的Markdown 括在方括号中，然后将链接添加在圆括号中。

[![沙漠中的岩石图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a16eeadbf38a4e7685dfc5d1cb80f099~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=847&h=566&s=57110&e=jpg&b=06566f?x-oss-process=image%2Finterlace%2C1 "Shiprock")](https://markdown.com.cn)

渲染效果如下：

表格（Table）

基本使用：

要添加表，请使用三个或多个连字符（---）创建每列的标题，并使用管道（|）分隔每列。您可以选择在表的任一端添加管道。

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

呈现的输出如下所示：

Syntax	Description
Header	Title
Paragraph	Text

单元格宽度可以变化，如下所示。呈现的输出将看起来相同。

| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |

温馨提示:

使用连字符和管道创建表可能很麻烦。为了加快该过程，请尝试使用Markdown Tables Generator。使用图形界面构建表，然后将生成的Markdown格式的文本复制到文件中。

设置表格的对齐方式：

您可以通过在标题行中的连字符的左侧，右侧或两侧添加冒号（:），将列中的文本对齐到左侧，右侧或中心。

| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |

呈现的输出如下所示：

Syntax	Description	Test Text
Header	Title	Here's this
Paragraph	Text	And more

格式化表格中的文字

表格不仅仅可以添加普通文本：

• 您可以在表格中设置文本格式。例如，您可以添加链接，代码（仅反引号（`）中的单词或短语，而不是代码块）和强调。
• 您不能添加标题，块引用，列表，水平规则，图像或HTML标签。

在表中转义管道字符

您可以使用表格的HTML字符代码（|）在表中显示竖线（|）字符。

代码块（Fenced Code Block）

基本使用：

Markdown基本语法允许您通过将行缩进四个空格或一个制表符来创建代码块。如果发现不方便，请尝试使用受保护的代码块。根据Markdown处理器或编辑器的不同，您将在代码块之前和之后的行上使用三个反引号（(```）或三个波浪号（~~~）。

```
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

呈现的输出如下所示：

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Tip:要在代码块中显示反引号？请参阅了解如何转义它们。

语法高亮

许多Markdown处理器都支持受围栏代码块的语法突出显示。使用此功能，您可以为编写代码的任何语言添加颜色突出显示。要添加语法突出显示，请在受防护的代码块之前的反引号旁边指定一种语言。

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

呈现的输出如下所示：

{ "firstName": "John", "lastName": "Smith", "age": 25 }

脚注（FootNote）

此处摘选自官方文档：markdown.com.cn/extended-sy...

笔者也不知道这一块主要是拿来干啥的，欢迎评论区补充一下。。。

作用：

脚注使您可以添加注释和参考，而不会使文档正文混乱。当您创建脚注时，带有脚注的上标数字会出现在您添加脚注参考的位置。读者可以单击链接以跳至页面底部的脚注内容。

基本使用：

要创建脚注参考，请在方括号（[^1]）内添加插入符号和标识符。标识符可以是数字或单词，但不能包含空格或制表符。标识符仅将脚注参考与脚注本身相关联-在输出中，脚注按顺序编号。

在括号内使用另一个插入符号和数字添加脚注，并用冒号和文本（[^1]: My footnote.）。您不必在文档末尾添加脚注。您可以将它们放在除列表，块引号和表之类的其他元素之外的任何位置。

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

呈现的输出如下所示：

Indent paragraphs to include them in the footnote.

`{ my code }`

Add as many paragraphs as you like.

标题编号（Heading ID）

基本使用：

许多Markdown处理器支持标题的自定义ID - 一些Markdown处理器会自动添加它们。添加自定义ID允许您直接链接到标题并使用CSS对其进行修改。要添加自定义标题ID，请在与标题相同的行上用大括号括起该自定义ID。

### My Great Heading {#custom-id}

HTML看起来像这样：

<h3 id="custom-id">My Great Heading</h3>

链接到标题ID (#headid)

通过创建带有数字符号（#）和自定义标题ID的[标准链接]((/basic-syntax/links.html)，可以链接到文件中具有自定义ID的标题。

Markdown	HTML	预览效果
[Heading IDs](#Markdown HTML 预览效果 Heading IDs Heading IDs Heading IDs "#heading-ids")	[Heading IDs](#Markdown HTML 预览效果 Heading IDs Heading IDs Heading IDs "#heading-ids")	Heading IDs

其他网站可以通过将自定义标题ID添加到网页的完整URL（例如Heading IDs）来链接到标题。

定义列表（Definition List）

基本使用：

一些Markdown处理器允许您创建术语及其对应定义的定义列表。要创建定义列表，请在第一行上键入术语。在下一行，键入一个冒号，后跟一个空格和定义。

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

HTML看起来像这样：

<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term. </dd>
  <dd>This is another definition of the second term.</dd>
</dl>

呈现的输出如下所示：

删除线（Strikethrough）

基本使用：

您可以通过在单词中心放置一条水平线来删除单词。结果看起来像这样。此功能使您可以指示某些单词是一个错误，要从文档中删除。若要删除单词，请在单词前后使用两个波浪号~~。

~~世界是平坦的。~~ 我们现在知道世界是圆的。

呈现的输出如下所示：

世界是平坦的。 我们现在知道世界是圆的。

任务列表（Task List）

功能：

任务列表使您可以创建带有复选框的项目列表。

基本使用：

• 在支持任务列表的 Markdown 应用程序中，复选框将显示在内容旁边。
• 要创建任务列表，请在任务列表项之前添加破折号-和方括号[ ]，
• 在[ ]前面加上空格。
• 要选择一个复选框，请在方括号[x]之间添加 x 。

- [x] 学习
- [ ] 玩耍
- [ ] 唱歌

呈现的输出如下所示：

• 学习
• 玩耍
• 唱歌

Markdown 进一步学习推荐：

• Markdown 官方文档 - Markdown 的工作原理
• Markdown 官方文档 - 方言？
• 其他大佬的学习笔记