目录

• 前言
• 基本规范
• 目录
  • 目录基本语法
  • 目录使用规范
• 标题
  • 标题的语法
  • 标题的使用规范
• 段落
  • 段落的语法
  • 段落的使用规范
• 行内代码
  • 行内代码的语法
  • 行内代码的使用规范
• 代码块
  • 代码块的语法
  • 代码块的使用规范
• 引用块
  • 引用块的语法
  • 引用块的使用规范
• 斜体
  • 斜体的语法
  • 斜体的使用规范
• 粗体
  • 粗体的语法
  • 粗体的使用规范
• 删除线
  • 删除线的语法
  • 删除线的使用规范
• 超链接
  • 超链接的语法
  • 超链接的使用规范
• 图片
  • 图片的语法
  • 图片的使用规范
• 列表
  • 有序列表
    • 有序列表语法
    • 有序列表的使用规范
  • 无序列表
    • 无序列表语法
    • 无序列表的使用规范
  • 任务列表
    • 任务列表语法
    • 任务列表的使用规范
  • 列表与其他元素混排
    • 列表间混排
    • 列表与其他块级元素混排
• 表格
  • 表格的语法
  • 表格的使用规范
• 转义语法字符

前言

本文描述了 Markdown 格式的基本语法，并说明了相应的使用规范。

读者可通过复现本文的展示效果来完全掌握 Markdown 基础语法。

基本规范

禁止 在 Markdown 文本中使用 Emoji 表情。

禁止 在全角标点与其他字符之间添加空格。

中英文之间，中文与数字之间，数字与单位之间 必须 有空格。

文本与半角字符 (包括 Markdown 语法符号) 之间 必须 有空格:

全角标点与其他字符之间 **禁止** 有空格。

众所周知 `int i = 1;` 是一个标准的静态类型语言的赋值语句。

链接前后 可以 没有空格 (想突出链接部分的内容，可以加空格)。

左括号的右侧，与右括号的左侧，可以 没有空格。上一行就是例子。

全角冒号 可以 使用半角冒号加一个空格来代替。

目录

目录基本语法

若文章第一行的内容为:

[TOC]

则 Markdown 渲染器会自动在全文开始之前加入目录。

目录使用规范

目录 必须 单独占据一行。

禁止 出现多个目录。

标题

标题的语法

要创建标题，请在标题文本前添加一至六个 # 符号。

# 数量将决定标题的层次级别。

# 第一级标题

## 第二级标题

### 第三级标题

标题的使用规范

只能 使用第一、二、三、四级标题，禁止 使用第五级及更低级别的标题。

第一级标题 只能 是文章题目。

遇到需要使用第五级标题的情况则必须按二级标题将文本拆分多个文章，原来的二级标题变成各个新文章的题目。

段落

段落的语法

每行文本就是一个段落。

上面那句话就是一个段落，这句话是第二个段落。两个段落之间应该总是有一个空行。

段落的使用规范

禁止 在段落的开头使用空格 (spaces) 或制表符 (tab) 为段落添加缩进。

每个非空行的下一行 必须 是空行。

行内代码

行内代码的语法

行内代码用于引用较短的代码。在代码文本的两端添加反引号 (数字 1 左边的键) ` 即可实现 行内代码 (int i = 1) 的效果。

`行内代码`
`int i = 1`

但是，需要注意，如果要在行内代码使用一个反引号 `，则要使用两个反引号将这一个反引号包起来，同时在这一个反引号的左右两侧添加空格:

`` ` ``

类似地，如果需要再行内代码中使用两个反引号 ``，那么就需要用三个反引号将这两个反引号包起来，同时在这两个反引号的左右两侧添加空格:

``` `` ```

行内代码的使用规范

在引用非代码文本时，禁止 使用行内代码，应当 使用斜体。

代码块

代码块的语法

代码块是被两行 ``` (3 个反引号) 或两行 ~~~ (三个波浪线) 包围的多个段落。但 ``` 己成事实标准。

比如，现在要渲染一段 C 语言代码:

```c
int i = 1;
```

~~~C
int i = 1;
~~~

它们的渲染效果相同:

int i = 1;

如果不知道代码块内部是什么语言则在语言标识部分使用 plaintext:

```text
docker image ls -a | wc -l
```

其渲染结果为:

docker image ls -a | wc -l

代码块的使用规范

禁止 使用缩进的方式创建代码块。

必须 使用三个反引号的方式来创建代码块。

所有的代码块 必须 标明代码类型。纯文本使用 plaintext 作为类型。

引用块

引用块的语法

在文本前添加一个大于号 > 后接一个空格即表示该段为引用:

> 没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅

渲染效果：

没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅

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

> 没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅
>
> 鲁迅说得对。——周树人

渲染效果：

没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅

鲁迅说得对。——周树人

块引用可以嵌套。多个大于号表示嵌套深度:

> 没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅
>
> 鲁迅说得对。——周树人
>
>> 烧烤也好使。——沃兹基硕德
>>
>>> 带上啤酒更管用。——沃兹基硕德

渲染效果:

没有什么事情是睡一觉解决不了的。如果有，那就再睡一觉。——鲁迅

鲁迅说得对。——周树人

烧烤也好使。——沃兹基硕德

带上啤酒更管用。——沃兹基硕德

引用也可以带格式:

> 如果一顿烧烤不管用，就 **再来一顿**。
>
> |A|B|
> |---|---|
> |aa|bb|
> |aaa|bbb|

渲染效果:

如果一顿烧烤不管用，就 再来一顿。

A	B
aa	bb
aaa	bbb

引用块的使用规范

禁止 在引用块内使用标题语法，这会引发渲染问题。

禁止 超过一个段落的引用。

所有引用 必须 注明出处。

斜体

斜体的语法

在需要使用斜体的文本两端添加 _ 或 * 即可实现 斜体 效果:

_斜体_
*斜体*

但 * 己成事实标准。

斜体的使用规范

在引用较短的，别处的文本时，必须 使用斜体。

粗体

粗体的语法

在需要使用粗体的文本两端添加 __ 或 ** 均可实现 粗体 效果:

__粗体__
**粗体**

但 ** 己成事实标准。

粗体的使用规范

在表示强调的地方 必须 使用粗体。

删除线

删除线的语法

被 ~~ (两个波浪线) 包围的文本会被添加删除线:

~~服务器的地址为 192.168.1.3。~~

渲染结果为:

服务器的地址为 192.168.1.3。

删除线的使用规范

只能 在过期但不可删除的信息上使用删除线。

比如: 服务器的地址为 192.168.1.3 192.168.2.5。

超链接

超链接的语法

链接文本放在中括号内，链接地址放在后面的小括号中，链接 title (鼠标光标放于超链接之上才显示) 可选：

[超链接显示的名称](超链接地址 "超链接 title")

比如:

[度娘](https://www.baidu.com "度娘 title")

渲染效果为: 这是一个 度娘 链接。

超链接的使用规范

当超链接内容重要时 禁止 使用超链接语法。

图片

图片的语法

感叹号 ! 后接超链接语法即为图片语法:

![度娘图片](https://www.baidu.com/img/flexible/logo/pc/result.png "度娘图片 title")

其渲染结果为:

如果想给图片加上超链接，则只要把图片语法套在超链接语法的方括号内 (图片语法中 title 的优先级更高):

[图片语法](目的链接 "title")

[![度娘图片](https://www.baidu.com/img/flexible/logo/pc/result.png "度娘图片 title")](https://www.bing.com "度娘转 bing")

其渲染结果为:

图片的使用规范

能用文字描述的内容 禁止 使用图片。

禁止 使用带超链接的图片。

列表

有序列表

有序列表语法

有序列表是以数字 + 英文句号 + 空格为开始标志的多个行:

1. 吃饭
2. 睡觉
3. 打豆豆

渲染结果:

1. 吃饭
2. 睡觉
3. 打豆豆

注: 数字必须以 1 开始，不必有序，渲染器会自动纠正列表项的数字。 但不推荐乱用数字的写法。

缩进一个或多个列表项可创建嵌套列表:

1. 吃饭
   1. 睡觉
   2. 没睡醒
   3. 该吃饭了
2. 睡觉
3. 打豆豆

渲染结果:

1. 吃饭
   1. 睡觉
   2. 没睡醒
   3. 该吃饭了
2. 睡觉
3. 打豆豆

有序列表的使用规范

有序列表的序号 必须 连续。

所有嵌套列表 必须 使用两个空格作为缩进尺寸。

禁止 使用超过两层嵌套的列表。

无序列表

无序列表语法

无序列表是以减号 -、星号 * 或加号 + 标志开始的多个连续的行:

- 吃饭
- 睡觉
- 打豆豆

* 吃饭
* 睡觉
* 打豆豆

+ 吃饭
+ 睡觉
+ 打豆豆

为节约空间，这里只给以 - 为列表项开头标志的列表的渲染结果:

• 吃饭
• 睡觉
• 打豆豆

缩进一个或多个列表项可创建嵌套列表:

- 吃饭
  - 睡觉
  - 再睡一觉
  - 事情还没解决，再来一觉
- 睡觉
- 打豆豆

• 吃饭
  • 睡觉
  • 再睡一觉
  • 事情还没解决，再来一觉
• 睡觉
• 打豆豆

无序列表的使用规范

所有嵌套列表 必须 使用两个空格作为缩进尺寸。

禁止 使用超过两层嵌套的列表。

任务列表

任务列表语法

以 - [ ] 或 - [x] 开头的列表项为任务列表:

- [x] 任务一
- [ ] 任务二
- [ ] 任务三

注 1: 两个中括号间必须有空格才会被渲染成未完成的任务 [ ]。

注 2: 两个中括号间必须用 小写 x 代替空格才会被渲染成已经完成的任务。

任务列表也支持嵌套。为节省空间，省略例子。

任务列表的使用规范

所有任务列表被标记完成时，必须 在列表结尾记录标记时间。

所有嵌套列表 必须 使用两个空格作为缩进尺寸。

禁止 使用超过两层嵌套的列表。

列表与其他元素混排

列表间混排

三种列表可以混排:

1. 第一项
   - 吃饭
     - [x] 买菜
     - [x] 洗菜
     - [ ] 做饭
   - 睡觉
   - 打豆豆
2. 第二项
   - [x] 吃饭
     1. 不好吃
     2. 下次不来了
   - [ ] 睡觉
   - [ ] 继续吃
3. 第三项

渲染结果:

1. 第一项
   • 吃饭
     • 买菜
     • 洗菜
     • 做饭
   • 睡觉
   • 打豆豆
2. 第二项
   • 吃饭
     1. 不好吃
     2. 下次不来了
   • 睡觉
   • 继续吃
3. 第三项

列表与其他块级元素混排

给一个渲染例子:

```text
注意两个行内代码快的缩进
```

- C 语言的赋值语法
  
  ```c
  int i = 1;
  ```

- Golang 语言的赋值语法:
  > var i = 1;

> 注意两个引用块的缩进

渲染结果为:

注意两个行内代码快的缩进

• C 语言的赋值语法

  int i = 1;
  

• Golang 语言的赋值语法:

  var i = 1;

注意两个引用块的缩进

列表内还可以包含行内代码块，斜体与粗体，这里就不给例子了。

表格

表格的语法

要使用表格，需要使用三个或以上的连字符 --- 分隔表头与表体，并使用竖线 | 分隔每列。

| A col       | B col       |
| ----------- | ----------- |
| A col A row | B col A row |
| A col B row | B col B row |

渲染结果如下所示：

A col	B col
A col A row	B col A row
A col B row	B col B row

表格源代码的排版不影响表格的渲染结果:

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

Syntax	Description
Header	Title
Paragraph	Text

在连字符的左侧、右侧或两侧添加冒号 : 可以将表格中的文本对齐到左侧，右侧或中心。

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

渲染结果为:

Syntax	Description	Test Text
Header	Title	Here
Paragraph	Text	And more

表格的使用规范

表格中 仅可以 使用 链接, 行内代码, 斜体 和 粗体。

转义语法字符

要显示被 Markdown 语法包含的字符，在字符前面添加反斜杠字符:

\- 如果 `-` 没有被转义，渲染结果为无序列表

- 如果 - 没有被转义，渲染结果为无序列表

渲染结果:

- 如果 - 没有被转义，渲染结果为无序列表

• 如果 - 没有被转义，渲染结果为无序列表

不需要特意记需要被转义的字符。看到渲染结果不对再找哪个字符需要转义即可。