Markdown 是一种轻量级标记语言，目的是尽可能使其易于阅读和编写。

Markdown 由 John Gruber 在 2004 年创建，现在是世界上最流行的标记语言之一。

接下来会分两部分介绍，基础语法 和 扩展语法。

基本上，所有的 Markdown 编辑器都支持 John Gruber 原始设计文档中描述的 基触语法，扩展语法则要根据各个编辑器而异。

基础语法

标题

要创建标题，需要在文本前添加数字符号 #，并且和文本之间有空格相隔。

替代语法

你还可以在文本下方加上 == 或者 -- 来表示一级或者二级标题。

标题最佳实践

各个 Markdown 编辑器在处理标题与周围段落之间缺少空白行上并不一致。

所以为了兼容性，请用一个或多个空行分隔各个段落和标题。

段落

用空白行分隔一个或者多个段落。

段落最佳实践

段落开头不要用空格或制表符缩进段落。

字体

可以通过 加粗 或者 斜体 来强调文字。

如果要表示 斜体，可以用一个 * 或者 _ 将文字包起来。

如果要表示 加粗，可以用两个 * 或者 _ 将文字包起来。

如果要表示 斜体并加粗，可以用三个 * 或者 _ 将文字包起来。

字体最佳实践

在单词中使用 _ 来加粗或者变斜并不生效，这时候需要用 *。

引用

要创建标题，需要在文本前添加数字符号 >，并且和文本之间有空格相隔。

1

> 这里是一处引用。

渲染效果如下：

这里是一处引用。

多个段落引用

1
2
3

> 这里是一处引用。
>
> 这里是另外一处引用。

渲染效果如下：

这里是一处引用。

这里是另外一处引用。

嵌套引用

1
2
3

> 这里是一处引用。
>
>> 这里是一个嵌套引用。

渲染效果如下：

这里是一处引用。

这里是一个嵌套引用。

引用里使用其他元素

1
2
3
4
5

> ### 这里是引用中的标题
>
> 这里是一个普通的段落。
>
> 引用中可以**加粗**。

渲染效果如下：

这里是引用中的标题

这里是一个普通的段落。

引用中可以加粗。

有序列表

要创建有序列表，需要在文本前添加数字和 .，并且和文本之间有空格相隔。

数字不必按数字顺序排列，但是第一列应该以 1 开头。

缩进两个空格可以生成嵌套列表。

无序列表

要创建无序列表，需要在文本前添加 -，* 或者 +，并且和文本之间有空格相隔。

缩进两个空格可以生成嵌套列表。

列表里使用段落

1
2
3
4
5
6
7
8

* 第一项
* 第二项

  第二项里引用的段落一。

  第二项里引用的段落二。

* 第三项

渲染效果如下：

• 第一项

• 第二项

  第二项里引用的段落一。

  第二项里引用的段落二。

• 第三项

同理，Markdown 里的其他元素也能在列表里使用。

代码

如果要表示 代码，可以用反引号 ` 将文本包起来。

如果文本里有反引号需要转义，可以用双反引号 `` 将文本包起来。

水平线

要创建水平线，可以用三个或更多星号 *** ，破折号 --- 或下划线 ___ 。

渲染效果如下：

链接

要创建链接，需要将链接文本括在方括号中，例如[谷歌]，然后立即在其后加上括号中的 URL，例如（https://google.com)。

1

使用[谷歌](https://google.com)搜索引擎

渲染效果如下：

使用谷歌搜索引擎

添加标题

可以给链接添加一个标题，这样当鼠标悬浮在链接上一段时间时，标题会显示出来。

1

使用[谷歌](https://google.com "Google 搜索引擎很好用")搜索引擎

渲染效果如下：

使用谷歌搜索引擎

网址和邮件地址

如果要快速将 URL 或电子邮件地址转换为链接，可以将其放在尖括号中。

1
2
3

<https://www.wangyulue.com>

<wangyulue@gmail.com>

渲染效果如下：

https://www.wangyulue.com

wangyulue@gmail.com

格式化链接

链接也可以加粗或者变成斜体。

1
2
3

使用 **[谷歌](https://google.com)** 搜索引擎

使用 *[谷歌](https://google.com)* 搜索引擎

渲染效果如下：

使用 谷歌 搜索引擎

使用 谷歌 搜索引擎

引用式链接

引用式链接是一种特殊的链接，它使得链接在 Markdown 中更容易显示和阅读，文本的可读性也会变得更高。

1
2
3
4
5
6

使用 [谷歌][1] 搜索引擎

使用 [谷歌][2] 搜索引擎

[1]: https://google.com
[2]: https://google.com "Google 搜索引擎很好用"

渲染效果如下：

使用 谷歌 搜索引擎

使用 谷歌 搜索引擎

图片

要添加图像，需要三步操作

1. 首先要添加感叹号 !
2. 然后在方括号中替换文本（替换文本可以为空）
3. 再在圆括号中添加图像的 URL，URL 可以是相对路径也可以是绝对路径（与链接类似，图片也可以添加标题）

例如一下的写法：

1
2
3
4
5

![](./images/google-logo.png)

![logo](./images/google-logo.png "google logo")

![logo](https://github.githubassets.com/images/modules/logos_page/Octocat.png "github logo")

转变成 HTML 后如下：

1
2
3
4
5
6
7
8
9

<img src="./images/google-logo.png" alt="" />

<img src="./images/google-logo.png" alt="logo" title="google logo" />

<img
  src="https://github.githubassets.com/images/modules/logos_page/Octocat.png"
  alt="logo"
  title="github logo"
/>

渲染效果如下：

将图片变成链接

如果想图片变成链接，点击后可以跳转，参考如下写法：

1

[![logo](./images/google-logo.png "google logo")](https://www.google.com/)

渲染效果如下：

注意

Markdown 语法无法控制图片的宽高，但是可以在文档里使用 HTML 来控制图片的宽高，例如：

1	<img width="20%" src="https://github.githubassets.com/images/modules/logos_page/Octocat.png" alt="logo" title="google logo">

渲染效果如下：

转义字符

如果要显示原本用于格式化 Markdown 文档中的文本的文字字符，可以字符前面添加一个反斜杠 \；

1
2
3
4
5
6
7

\* 显示星号

\- 显示减号

\# 显示井号

\+ 显示加号

渲染效果如下：

* 显示星号

- 显示减号

# 显示井号

+ 显示加号

HTML

很多 Markdown 编辑器允许你在文档中插入 HTML，这有助于对文档做更细粒度的控制。

前面在图片一节的演示也说明了这一点。

再比如：

1

**这段文字是加粗的**，<em>这段文字是斜体</em>

渲染效果如下：

这段文字是加粗的，这段文字是斜体。

扩展语法

John Gruber 原始的设计文档写的非常好，但对于一些人来说还不够，于是就有了扩展语法。

不是所有 Markdown 编辑器都支持扩展语法语法。所以在使用前，有必要检查你的编辑器对扩展语法的支持程度。

一般来说，Github 上 Markdown 编辑器的兼容性做的很好，所以可以用它来练手。

表格

要添加表格，需要使用三个或多个连字符--- 创建各列的标题，并使用管道 | 分隔各列。

表格里也可以使用 markdown 中的其他语法，例如加粗、列表、链接、代码。

1
2
3
4

| **Markdown** | **HTML**            | **Render**        |
|--------------|---------------------|-------------------|
| # 一级标题   | `<h1>一级标题</h1>` | <h1>一级标题</h1> |
| ## 二级标题  | `<h2>二级标题</h2>` | <h2>二级标题</h2> |

渲染效果如下：

分割线 - 的长度只要不少于三，可以任意变化；文字和管道直接的空格长度也可以是任意的；这些都不会影响渲染。

对齐方式

可以在连字符--- 左侧或者右侧加上 : 来控制对齐方式

1
2
3
4

| **左对齐**       |     **居中**     |       **优对齐** |
|:--------------|:--------------:|--------------:|
| 靠左对齐         |     居中对齐     |         靠右对齐 |
| 靠左对齐靠左对齐 | 居中对齐居中对齐 | 靠右对齐靠右对齐 |

渲染效果如下：

在表格中使用管道符

如果想在表格中显示 | ， 可以使用其 HTML 字符 |。

1
2
3

| **显示管道符** |
|----------------|
| |         |

渲染效果如下：

代码块

可以使用用三个反引号 ``` 或者三个波浪号 ~~~ 将文本包起来形成代码块。

1
2
3
4
5
6

```
{
  "name": "Wanger",
  "age": 25
}
```

渲染效果如下：

1
2
3
4

{
  "name": "Wanger",
  "age": 25
}

语法高亮

在第一排三个反引号 ``` 后面加上语言名称可以使代码高亮

1
2
3
4
5
6

```json
{
  "name": "Wanger",
  "age": 25
}
```

渲染效果如下：

1
2
3
4

{
  "name": "Wanger",
  "age": 25
}

代码 diff

在第一排三个反引号 ``` 后面加上 diff 可以显示代码增减

1
2
3
4
5
6
7

```diff
  {
    "name": "Wanger",
-   "age": 25
+   "age": 26
  }
```

渲染效果如下：

1
2
3
4
5

  {
    "name": "Wanger",
-   "age": 25
+   "age": 26
  }

删除线

如果要表示 被删除的文字，可以用两个 ~ 将文字包起来。

1

~~这是被删除的文字~~

渲染效果如下：

这是被删除的文字

任务列表

你可以创建带有复选框的任务列表。

1
2
3

- [x] 吃苹果
- [ ] 吃草莓
- [ ] 吃葡萄

渲染效果如下：

• 吃苹果
• 吃草莓
• 吃葡萄

表情符号

大部分情况下，你可以简单地从 Emojipedia 等来源复制一个表情符号，然后粘贴到文档中。

1
2
3

太搞笑了！ 😂

调皮 😜

渲染效果如下：

这太搞笑了！ 😂

调皮 😜

自动网址链接

很多 Markdown 编辑器会自动将 URL 转换为链接。即使你没有用尖括号把 URL 包起来。

1
2
3

https://www.google.com/

<https://www.google.com/>

渲染效果如下：

https://www.google.com/

https://www.google.com/

参考文档

Markdown guide