让读写文档变得更简单 - Markdown

一、Markdown简介

如果你使用了很久的github，却不知道什么是Markdown，那你真的非常有必要了解一下了（实际上编写本文用的正是Markdown，这是一项非常有用并且很简单的文本编辑技能，特别是使用了Markdown编辑器之后）。

Markdown是一种轻量级标记语言，类似于HTML，由约翰·格鲁伯（英语：John Gruber）创建于2004年。Markdown 致力于使阅读和创作文档变得容易，因此可读性是它的最高准则。为此，Markdown不使用任何标签和格式化语法，而是仅仅使用简单的标记（如一个#加一个空格，它表示后面是一个一级标题）来生成文档结构。一个示例性的Markdown可能如下：

这是一个在线Markdown编辑器mdeditor的示例页面。左侧所写的就是Markdown代码，它几乎与纯文本没有太大区别，右侧正是该代码在网页上的显示效果。

我们先来观察左侧的Markdown语法，它的结构大致如下：

于是在右侧，你可以看到网页中的显示结果如下：

与使用普通文本编辑器编写文档不同的是，该文档里包含了许多特殊的标记。如一个#加一个空格可以标识后面的文字是一级标题。用一对星号(*)包裹一段文本，表示该文本需要加粗等。

这些标记大多数情况下不需要你记忆，因为在线编辑器会为你提供这样的工具栏：

现在只要你选中一段文本，然后点击“加粗”，编辑器就会自动为你在该文本两侧各加两个*，于是该文本就会显示为加粗文本。如：

现在“github”的左右两侧各新增了两个星号标记：

显示结果为：

如果你希望为文档生成一个目录，只需要点击右侧“目录”，编辑器就会为你插入这样一个标记（“目录”两字为目录名称，可任意修改）：

这样你的文档里就会出现类似这样的一个目录：

这里的目录内容来自于当前文档内所使用的的所有标题，并且点击可以链接到该标题下。使用起来非常简单，不是吗？

当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如：GitHub、CSDN、简书、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge等。如果你是一个资深的github用户，那么你最熟悉的应该就是每次新建项目时都会生成的README.md文件吧，它可以是该项目的描述文件，或者相关教程，而它正是基于Markdown语法的（md后缀正是Markdown的缩写）。

虽然有了Markdown编辑器，我们在编写md文件时很少需要手写Markdown标记，但是如果要熟练使用Markdown，掌握常见的Markdown语法还是必不可少的。

二、Markdown常见语法

1. 标题

Markdown总共支持六级标题（对应于HTML中h1~h6六级标题），标准格式为：

一级标题为一个#加一个空格，二级标题为两个#加一个空格，以此类推。结果如下：

此外，一级和二级标题还可以使用如下的标记（“=”和“-”的数量任意）：

我展示的是一级标题
=================

我展示的是二级标题
-----------------

2. 段落和文本

如果你只需要一个普通的段落，那么它不需要任何标记，直接像在普通的文本编辑器中一样编写即可。如：

Markdown文件与显示结果几乎没有差别。

如果你希望对其中某些文本添加特定的文本样式，那么你可以为这些文本添加专门的标记。常见的文本样式如下：

它们产生的效果如下：

3. 列表

主要包括有序列表和无序列表（不同的Markdown编辑器还可能提供其他的列表类型）。无序列表使用“*”、“+”或“-”加一个空格来标记，如：

* 第一项
* 第二项

+ 第一项
+ 第二项


- 第一项
- 第二项

显示结果为：

• 第一项
• 第二项

• 第一项
• 第二项

• 第一项
• 第二项

有序列表使用数字加“.”及一个空格来标记，如：

1. 第一项
2. 第二项
3. 第三项

显示为：

1. 第一项
2. 第二项
3. 第三项

如果需要显示嵌套列表，只需要在子级列表项前加四个空格即可（这里csdn的编辑器将子级无序列表显示为有序列表，属于编辑器特性，在其他编辑器中行为可能略有不同）：

 1. 第一项：
    - 第一项嵌套的第一个元素
    - 第一项嵌套的第二个元素
 2. 第二项：
    - 第二项嵌套的第一个元素
    - 第二项嵌套的第二个元素

1. 第一项：
   • 第一项嵌套的第一个元素
   • 第一项嵌套的第二个元素
2. 第二项：
   • 第二项嵌套的第一个元素
   • 第二项嵌套的第二个元素

4. 区块

一个区块的样式如下：

这是一个区块

多层嵌套：

最外层

第一层嵌套

第二层嵌套

它的语法非常简单，就是在文字前面加“> ”，多级区块使用多个>，如：

> 这是一个区块

> 最外层
> > 第一层嵌套
> > > 第二层嵌套

5. 代码块

如果是一段文本中间出现的少量代码块，你可以用反引号`（位于tab键的正上方，数字键“1”的左侧，使用英文输入法即可输入反引号）来标记，如：

这里有一个`print`函数

它显示为：这里有一个print函数。显示效果因编辑器及所用主题而异。

如果需要引用大段代码块，可以使用两种语法：

1. 使用四个空格或一个tab符进行缩进
2. 使用三个反引号标记一个代码段，支持标注所用的语言

如：

    function returnTrue(){
      return true;
    }

或（反引号写法不便于嵌套，因此这里用图片展示）：

显示结果即为：

function returnTrue(){
    return true;
}

这里显示为黑色，是因为在编辑器设置中启用了黑色的代码块风格，如果编辑器提供了其他风格，它可能看起来与这里不完全一致。如果不指定所用语法，只是使用三个反引号，编辑器可能无法进行代码高亮，这样通常不便于阅读。

6. 超链接

编写web文档时经常出现超链接，Markdown使用如下语法来标记一个超链接：

[链接名称](链接地址)

或

<链接地址>

例如：

这是一个链接 [菜鸟教程](https://www.runoob.com)

<https://www.runoob.com>

将显示为：

除此之外，链接地址还可以使用变量来代替，然后在文档末尾为变量指定链接地址，如：

这个链接用 1 作为网址变量 [Google][1]

//在文档尾添加
[1]: http://www.google.com/

该模式参考了论文中使用[1]这样的语法标记引用，然后在论文末尾标注引用的习惯。使用数字作为变量只是一个习惯，理论上你可以使用任意变量名。

7. 图片

Markdown的图片语法通常非常简单：

![alt 属性文本](图片地址)

![alt 属性文本](图片地址 "可选标题")

alt 属性文本为图片无法加载时的替代文本，括号内是图片地址，允许指定标题。如：

![markdown](https://www.mdeditor.com/images/logos/markdown.png "markdown")

这样在预览区就会出现目标图片。

大多数Markdown编辑器不需要手动插入图片，你可以直接复制一张图片，然后粘贴到文档内即可（甚至是拖拽到文档内，这取决于编辑器实现），编辑器会自动为你生成标记。

8. 表格

表格的语法相比于HTML来说也简单了很多，一个简单的表格实现如下：

|  表头   | 表头  |
|  ----  | ----  |
| 单元格  | 单元格 |
| 单元格  | 单元格 |

它会生成这样一张表格：

表头	表头
单元格	单元格
单元格	单元格

第二行用于分隔表头和表格体。在这里你还可以指定表格的对齐方式，它通过添加引号来实现：

| 左对齐 | 右对齐 | 居中对齐 |
| :-----| ----: | :----: |
| 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 |

结果如下：

左对齐	右对齐	居中对齐
单元格	单元格	单元格
单元格	单元格	单元格

冒号位于左侧即为左对齐，位于右侧为右对齐，两侧都有冒号即为中间对齐（通常这种情况不需要添加冒号）。这里用于分隔的减号（-）数量没有强制要求。

9. 其他

除了上面介绍的常见标记外，Markdown还有很多非常强大的标记，比如插入数学公式、UML图、甘特图、流程图等，这些功能是随着文档编写的需要逐步添加到Markdown语法的。由于较为复杂并且不是很常用，这里不再详述，只举几个例子：

数学公式：

$$
\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.
$$

生成：
$\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.$Γ(z)=∫0∞​tz−1e−tdt.
甘特图：

gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to mermaid
        section 现有任务
        已完成               :done,    des1, 2014-01-06,2014-01-08
        进行中               :active,  des2, 2014-01-09, 3d
        计划中               :         des3, after des2, 5d

生成：

UML时序图：

sequenceDiagram
张三 ->> 李四: 你好！李四, 最近怎么样?
李四-->>王五: 你最近怎么样，王五？
李四--x 张三: 我很好，谢谢!
李四-x 王五: 我很好，谢谢!
Note right of 王五: 李四想了很长时间, 文字太长了<br/>不适合放在一行.

李四-->>张三: 打量着王五...
张三->>王五: 很好... 王五, 你怎么样?

流程图：

graph LR
A[长方形] -- 链接 --> B((圆))
A --> C(圆角长方形)
B --> D{菱形}
C --> D

生成：

注意：这里的数学图表都需要放在下面的标记内才能显示为图表：

总结

Markdown的入门门槛非常低，在使用在线编辑器的情况下，几乎和编写普通的文本没有什么差别（如果你的文档没有流程图之类的）。如果你希望在各个博客平台写博客文章，那么Markdown是你必备的基础技能之一；如果你想为自己的github项目编写一个良好的README.md说明文档，那么请你务必抽几个小时了解一下Markdown。

如果你需要学习Markdown教程，这里有两个推荐：
菜鸟教程 - Markdown教程
MDN中文文档 - Markdown

如果你现在就想找一个在线编辑器练练手，那么这里有个很好的推荐：
MdEditor

实际上当你阅读完本文，你应该已经具备了在一个在线编辑器中编写一份简单的Markdown文档的能力（即使不具备，在线编辑器的新手引导也足够用了，范例中包含了大部分你可能用到的Markdown语法）。所以赶紧上手试一下吧。