---
title: 一些你需要知道的常规语法
author: wuli 坤坤
date: 2021-03-26
---

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。由于 Markdown 的轻量化、易读易写特性，并且对于图片，图表、数学式都有支持，目前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。如 GitHub、Reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge、简书等，甚至还能被用来撰写电子书。

Markdown 的语法没有唯一的官方标准，毕竟 Aaron Swartz[^swartz] 英年早逝。但是开源界普遍接受 GFM（GitHub Flavored Markdown）作为既定事实标准。所以我们也按照这个标准进行规范，另外对 Markdown 可以多种表达的语法结构做一定约束。

:::info
HackMD 这个网站提供了很多更高级的语法，我觉得也值得一用，只是没有那么强的普适性。
:::

[^swartz]: Aaron Swartz（19xx-20xx），Markdown 的发明者。

## 最最常用的语法速查

Markdown 的语法不多，核心部分的语法更少。

:::success
在 HackMD 网站上最快的查询方式就是在编辑的时候点击这个页面最上方那个问号:question:，基本的语法就展示出来了。
:::

### 标题

Markdown 的标题有三种写法，只需要记忆和使用一种（单侧形式）：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

### 包围的文字标记

| 标记 | 语法 | 示例 |
| ------------------------------------ | ------------------ | -------------- |
| 加粗强调 | 两个 `**` 包围起来 | **加粗**的内容 |
| 斜体强调^（中文场景下并不推荐使用）^ | 一个 `*` 包围起来 | *斜体*的内容 |

:::warning
下面几个标记是扩展的 Markdown 语法，不一定全部支持，但是 HackMD 网站支持。
:::

| 标记 | 语法 | 示例 |
| -------- | ------------------------ | ------------------------------------- |
| 高亮强调 | 两个等号 `==` 包围起来 | ==高亮==的内容 |
| 插入强调 | 两个加号 `++` 包围起来 | ++插入++的内容 |
| 删除 | 两个波浪号 `~~` 包围起来 | ~~删除~~的内容 |
| 上标 | 一个转折号 `^` 包围起来 | 需要被^上标^的内容 |
| 下标 | 一个波浪号 `~` 包围起来 | 需要被~下标~的内容 |
| 行内公式 | 一个美元号 `$` 包围起来 | 勾股定理 $a^2 + b^2 = c^2$ |
| 行内代码 | 一个反撇号 \` 包围起来 | Python 里面的 `print('Hello World!')` |

:::success
你可以注意到：

- ==行内公式==会使用斜体罗马字体来表示变量，正体罗马字体来表示函数和方程。公式的语法称为 $\LaTeX$[^latex]。
- ==行内代码==会使用等宽非衬线的英文字体来表示代码（目的是便于对齐和区分大写 I 和小写 l，数字 0 和字母 O 等），同时还会在代码周围加上背景框，略作区分。
:::

[^latex]: **LaTeX**（/ˈlɑːtɛks/，常被读作 /ˈlɑːtɛk/ 或 /ˈleɪtɛk/，写作「$\LaTeX$」），是一种基于 $\TeX$ 的排版系统，它非常适用于生成复杂表格和数学公式，高印刷质量的科技和数学、物理文档。

### 描述性文本标记

#### 链接的写法

[text](link "title")

其中：

- **text**：是链接的文本，就是文档渲染出来能看到的文字。
- **link**：无需多言，就是链接本身。
:::spoiler 链接本身就很有意思，它包含了**协议**和**定位**两部分。
- 通常我们都使用 `http:/https:` 的**超文本传输协议**来访问网页
- 也有时候我们可以使用 `ftp:` 等**文件传输协议**，或者是 `weibo:` 这样的**私有协议**
- 定位除了向常见的**网址链接**之外，也可以是锚链接 `#anchor`，定位到网页的具体位置，在 markdown 中，每一级的标题都可以当作锚链接使用
:::
- **title**：是当我们的鼠标指向链接的 text 时，悬停后出现的提示文本

如果你只想展示一个链接也可以：

- https://www.google.com
- 或者用 `<>` 把链接包围起来 <mailto:[e-mail]>

#### 图片的写法

![text](link "title")

==实际上图片只比链接多了一个感叹号`!`==，其中：

- **text**：是图片的文本，就是图片不能正常加载的时候显示的替代文字。
- **link**：是图片的链接
:::spoiler 本地图片没有链接怎么办？
- 把图片上传到公共==图床==服务器，生成一个公开链接
- 把图片和 markdown 文件放到一起，然后使用相对路径访问本地图片资源
:::
- **title**：是当我们的鼠标指向图片时，悬停后出现的提示文本

### 块级别的文本标记

#### 无序列表

减号 `-`、加号 `+`、星号 `*` 加空格都可以引导一个无序列表：

- `- `项目一
- `- `项目一
- `- `项目一

* `* `项目二
* `* `项目二

+ `+ `项目三
+ `+ `项目三

#### 有序列表

数字加点加空格就可以引导一个有序列表：

1. 项目1
2. 项目2
3. 项目3
6. 项目4

#### 块级代码

用三个反撇围出一块区域，区域内都是代码，不会被识别成任何 Markdown

这个区域内的东西随便写
        大量的空格和 **语法** 都是允许的
code is better for this.

#### 块级公式

用两个美元符号围出一块区域，区域内都是公式

$$
-\frac{1}{m}=\frac{\sum_{i=1}^n{X_iY_i}-\frac{1}{n}\sum_{i=1}^n{X_i\sum_{i=1}^n{Y_i}}}{\sum_{i=1}^n{X_{i}^{2}-\frac{1}{n}\left(\sum_{i=1}^n{X_i}\right)^2}}\\
\frac{1}{m}\lg C=\frac{1}{n}\left(\sum_{i=1}^n{Y_i+\frac{1}{m}\sum_{i=1}^n{X_i}}\right)\\
$$

#### 引用

一段话如果是引用的，就用大于号加空格引导

> 我家门前有两棵树，一棵是枣树，另一棵也是枣树。
> —— 鲁迅

---

:::warning
分割线，下面是进阶知识
:::

## 常见错误和约束

### 1️⃣多级标题的使用

> 多级标题约定使用「**单侧 `#` 号表示**」也即：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

#### 需要注意的地方

1. 使用单侧 `#` 号，而非双侧形式 `# 一级标题 #`
2. `#` 号和标题之间必须添加一个`空格`
3. 标题行前后需要添加`空行`
4. 多级标题需要层级连续使用，不要跳级
5. 不使用三连字符法创建标题 `---` 和 `===` （deprecated）

### 2️⃣段落间的空行

> Markdown 任意段落之间必须使用一个`空行`隔开：

# 标题下面要空行

段落1，哪怕很短，下一个段落也要空行。

段落2，下一个段落是有序列表，也需要空行：

1. 这是有序列表1，下一个序号不需要空行
2. 这是有序列表2，可以通过缩进混合无序列表使用
    - 这是无序列表，下一个表项也不需要空号
    - 列表结束之后也需要空行

> 这是一段引用。
> 
> 引用内部形成段落也需要空行⬆️。
> 
> > 引用层级可以嵌套

上面正确的语法会被各种编辑器和以及网页正确的 parse 和渲染：

段落1，哪怕很短，下一个段落也要空行。

段落2，下一个段落是有序列表，也需要空行：

1. 这是有序列表1，下一个序号不需要空行
2. 这是有序列表2，可以通过缩进混合无序列表使用
- 这是无序列表，下一个表项也不需要空号
- 列表结束之后也需要空行

> 这是一段引用。
>
> 引用内部形成段落也需要空行⬆️。
>
> > 引用层级可以嵌套

#### 需要注意的地方

1. Markdown 中所有连续空格以及空行都会被识别成一个，因此**不要在 Markdown 中使用连续空格和连续空行来排版**
2. Markdown 中单个换行符会被识别成 `</br>` 自闭合标签，而非段落标签 `<p></p>`，因此记得**段落之间保持的一个单独的空行**
3. **不要在一个段落中使用换行符**来进行硬回车，会被识别成一个空格，一个段落只占一行
4. 所有段落级别的语法都需要写成**标记符+空格**：例如 `1. 有序列表`，`- 无序列表`，`> 引用`，`# 标题`

### 引入代码

> 块级代码统一使用三个反引号 ` 符号，而非使用8个空格的缩进方式

块级代码使用三个反引号的包围结构有以下好处：

1. 清晰的开始和结束边界
2. 可以指明代码块的语法高亮语言

        code here

#### 需要注意的地方

1. 但凡段落中出现**类、方法、变量、参数**，需要使用行内代码一个反引号符号 ` 包围
2. 块级代码需要指明使用的语言，确保语法高亮正确解析反引号
3. 再次强调，块级代码前后都需要一个空行

### 其他的一些约束

1. 英文单词应该与中文间有一个空格的间隔，标点符号前后都不应该有空格，参见[盘古之白](https://sspai.com/post/33549)，点名表扬 @panpan.wu 规范的空格书写格式
2. 插入图片和链接优先使用行内引用表达式，而非参考引用表达式
3. 文档第一行必须以一级标题 `# 文档标题` 开始，或二级标题 `## 文档章节` 开始，不能没有标题没有层级，或则随意从三级、四级标题开始
4. Markdown 中的语法符号都是英文半角符号，切勿使用中文全角符号

## GFM 参考

下面给大家附上 GitHub Flavored Markdown 语法手册，其中具有多种写法的语法点，我都在上面做了约束，下面的方便不熟悉语法的同学速查。大家也可以在 GitHub 官方网站中查看到更为详细的信息：[GFM 文档](https://github.github.com/gfm/)

### 标题

Markdown 语法：

# 第一级标题 `<h1>` 
## 第二级标题 `<h2>` 
###### 第六级标题 `<h6>` 

### 强调

Markdown 语法：

*这些文字会生成`<em>`*
_这些文字会生成`<u>`_

**这些文字会生成`<strong>`**
__这些文字会生成`<strong>`__

效果如下：

*这些文字会生成`<em>`*
_这些文字会生成`<u>`_

**这些文字会生成`<strong>`**
__这些文字会生成`<strong>`__

### 列表

#### 无序列表

Markdown 语法：

* 项目一 无序列表 `* + 空格键`
* 项目二
* 项目二的子项目一 无序列表 `TAB + * + 空格键`
* 项目二的子项目二

效果如下：

* 项目一 无序列表 `* + 空格键`
* 项目二
* 项目二的子项目一 无序列表 `TAB + * + 空格键`
* 项目二的子项目二

#### 有序列表

Markdown 语法：

1. 项目一 有序列表 `数字 + . + 空格键`
2. 项目二 
3. 项目三
1. 项目三的子项目一 有序列表 `TAB + 数字 + . + 空格键`
2. 项目三的子项目二

效果如下：

1. 项目一 有序列表 `数字 + . + 空格键`
2. 项目二
3. 项目三
1. 项目三的子项目一 有序列表 `TAB + 数字 + . + 空格键`
2. 项目三的子项目二

#### 任务列表（Task lists）

Markdown 语法：

- [ ] 任务一 未做任务 `- + 空格 + [ ]`
- [x] 任务二 已做任务 `- + 空格 + [x]`

效果如下：

- [ ] 任务一 未做任务 `- + 空格 + [ ]`
- [x] 任务二 已做任务 `- + 空格 + [x]`

### 图片

Markdown 语法：

![GitHub set up](http://zh.mweb.im/asset/img/set-up-git.gif)
格式: ![Alt Text](url)

效果如下：


### 链接

Markdown 语法：

email <[e-mail]>
[GitHub](http://github.com)
自动生成连接  <http://www.github.com/>

效果如下：

Email 连接： <[e-mail]>
[连接标题Github网站](http://github.com)
自动生成连接像： <http://www.github.com/> 这样

### 区块引用

Markdown 语法：

某某说:

> 第一行引用
> 第二行费用文字

效果如下：

某某说:

> 第一行引用
> 第二行费用文字

### 行内代码

Markdown 语法：

像这样即可：`<addr>` `code`

效果如下：

像这样即可：`<addr>` `code`

### 多行或者一段代码

Markdown 语法：

    function fancyAlert(arg) {
        if(arg) {
        $.facebox({div:'#foo'})
        }
    
    }

效果如下：

function fancyAlert(arg) {
    if(arg) {
    $.facebox({div:'#foo'})
    }

}

### 表格

Markdown 语法：

第一格表头 | 第二格表头
--------- | -------------
内容单元格 第一列第一格 | 内容单元格第二列第一格
内容单元格 第一列第二格 多加文字 | 内容单元格第二列第二格

效果如下：

第一格表头 | 第二格表头
--------- | -------------
内容单元格 第一列第一格 | 内容单元格第二列第一格
内容单元格 第一列第二格 多加文字 | 内容单元格第二列第二格

### 删除线

Markdown 语法：

加删除线像这样用： ~~删除这些~~

效果如下：

加删除线像这样用： ~~删除这些~~

### 分隔线

以下三种方式都可以生成分隔线：

***

*****

- - -