markdown-tutorial

Markdown是一个将文本转化为HTML的工具。简单来说，Markdown是一个兼顾可读性与易用性的轻量级标记体系。Markdown并不追求大而全，它只关心HTML里最常用的几个标记，对于一些不常用的标记它允许直接将HTML标记插入文本。

GFM & SM

GitHub 全站支持 “GitHub 风格的 Markdown 语法”（简称 GFM），你可以用它来书写 issue、pull request（以下简称 “PR”）和各种评论。它和标准 Markdown 语法（SM）相比，存在一些值得注意的差异，并且增加了一些额外功能。

如果你想了解在书写 issue、评论和 PR 描述时有哪些技巧（比如任务清单这样的高级功能），你应该读一下GitHub 上的书写方式

基本用法

标题

一共有六级标题，用1-6个#来表示：

# 一级标题
## 二级标题
###### 六级标题

效果：

一级标题

二级标题

六级标题

除了用#来表示标题，还可以用在底部添加=（任意数量）的方式表示一级标题和二级标题：

一级标题
=
二级标题
==

效果：

一级标题

二级标题

斜体、粗体、删除线

通过成对的**和__表示加粗字体；通过成对的*和_表示倾斜字体；通过成对的~~表示删除字体：

斜体、粗体、删除线可混合使用，删除线为GFM新增语法

SM语法会把所有成对的_转换为斜体，但GFM不会处理英文单词内的那些下划线。所以在GFM中，如果你确实要把单词中的某一部分设置为斜体，可以使用*

语法	效果
*斜体1*	斜体1
_斜体2_	斜体2
**粗体1**	粗体1
__粗体2__	粗体2
这是一个 ~~删除线~~	这是一个 删除线
***斜粗体1***	斜粗体1
___斜粗体2___	斜粗体2
***~~斜粗体删除线1~~***	斜粗体删除线1
~~***斜粗体删除线2***~~	斜粗体删除线2

分隔线

在一行中使用三个或三个以上的*、-或_可以添加分隔线，其中可以有空白，但是不能有其他字符：

***
---
___

效果：

---

引用

行首使用>加上一个空格表示引用，可嵌套使用：

> 这里是引用的内容
> > 嵌套内容

效果：

这里是引用的内容

嵌套内容

列表

使用*、+或-加上一个空格表示无序列表，列表可嵌套：

* item1
* item2
* item3

+ item1
+ item2
+ item3

- item1
- item2
- item3

* 编程语言
    * 脚本语言
        * Python

效果：

• item1
• item2
• item3

• item1
• item2
• item3

• item1
• item2
• item3

• 编程语言
  • 脚本语言
    • Python

使用数字加英文句号加空格表示有序列表，和无序列表一样，也可以嵌套：

1. item1
2. item2
7. 不用担心数字不对，显示的时候我们会自动把这行的 7 纠正为 3

1. 这是一级的有序列表，数字1还是1
   1. 这是二级的有序列表，阿拉伯数字在显示的时候变成了罗马数字
      1. 这是三级的有序列表，数字在显示的时候变成了英文字母

效果：

1. item1
2. item2
3. 不用担心数字不对，显示的时候我们会自动把这行的 7 纠正为 3

---

1. 这是一级的有序列表，数字1还是1
   1. 这是二级的有序列表，阿拉伯数字在显示的时候变成了罗马数字
      1. 这是三级的有序列表，数字在显示的时候变成了英文字母

代码

SM会把每行前面空四格的文本块转换为代码块，而GFM还可以通过成对的```表示代码块，同时后面可以加上编程语言的名字，为代码块指定语法着色效果（`在键盘数字1的左边）：

代码段落则是在每行文字前加4个空格或者1个缩进符表示

效果：

代码片段
    代码段落

GFM使用Linguist来进行语言识别和语法着色。你可以在语言 YAML 文件中查证哪些语言标识符是有效的。

如果不需要代码高亮，可以用下面的方式禁用：

不需要高亮的代码片段

标记

通过成对的`和``表示代码。（`在键盘数字1的左边）：

`标记`

效果：

标记

链接

以中括号标记显示的链接文本，后面紧跟用小括号包围的链接。如果链接有title属性，则在链接中使用空格加"title属性"：

[链接文本](url 'url title')

效果：

Merrier说

图片

图片的使用方法基本上和链接类似，只是在中括号前加叹号。

Markdown不能设置图片大小，如果必须设置则应使用HTML标记<img>，见高级用法中的HTML标签

这是一张图片：![图片替代文本](image url 'image title')

效果：

这是一张图片：

表格

用|表示表格纵向边界，表头和表内容用-隔开，并可用:进行对齐设置，两边都有:则表示居中，若不加:则默认左对齐：

表格中可以添加图片、加粗字体、斜体等markdown元素

|默认居左|        居左      |       居右       |       居中      |
|------|:-----------------|----------------:|:--------------:|
|默认居左|只有左侧有`:`表示居左|只有右侧有`:`表示居右|两侧都有`:`表示居中|

效果：

默认居左	居左	居右	居中
默认居左	只有左侧有:表示居左	只有右侧有:表示居右	两侧都有:表示居中

高级用法

换行

在文字的末尾使用两个或两个以上的空格来表示换行。

引用链接/图片

和基础用法里面的链接类似，一般应用于多个不同位置使用相同链接。通常分为两个部分，调用部分为[链接文本][ref]；定义部分可以出现在文本中的其他位置，格式为[ref]: http://some/link/address，图片类似，在中括号前加!即可：

ref中不区分大小写。

[ref]: http://merrier.wang

这是一个[引用链接][ref]

效果：

这是一个引用链接

自动链接

使用<>，可以为输入的URL或者邮箱自动创建链接：

<[email protected]>

效果：

[email protected]

转义字符

Markdown中的转义字符为\，可以转义的有：

语法	效果
\\	|
\*	*
\_	_
\{\}	{}
\[\]	[]
\(\)	()
\#	#
\+	+
\-	-
\.	.
\!	!

HTML标签

markdown中可以插入html标签，包括<kdb> <b> <i> <em> <sup> <sub> <br>，如：

语法	效果
[回到顶部](#markdown-tutorial)	回到顶部
使用 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> 重启电脑	使用 Ctrl+Alt+Del 重启电脑
<pre>代码块</pre>	代码块
<b>加粗字体</b>	加粗字体

关于可用的标签和属性有哪些，你可以在github/markup这个项目中找到一份完整的清单。

锚点

效果：

其实在Markdown文件中，每一个标题都是一个锚点，和HTML的锚点（#）类似，比如我们

语法	效果
[回到顶部](#markdown-tutorial)	回到顶部
**[⬆ back to top](#table-of-contents)**	⬆ back to top

不过要注意，标题中的英文字母都会被转化为小写字母。

以前GitHub对中文支持的不好，所以中文标题不能正确识别为锚点，但是现在已经没问题啦！

任务列表

- [x] 内容1表示内容1已完成，- [ ] 内容2表示内容2未完成，一般使用这个功能来标注某个项目各项任务的完成情况

- [x] 已完成
- [ ] 未完成

效果：

• 已完成
• 未完成

表情

Github的Markdown语法支持添加emoji表情，输入不同的符号码（两个冒号包围的字符）可以显示出不同的表情。

比如:blush:，可以显示:blush:。

具体每一个表情的符号码，可以查询GitHub的官方网页http://www.emoji-cheat-sheet.com。

但是这个网页每次都打开奇慢。。所以有位大牛整理到了自己的repo中，大家可以直接在此查看emoji。

旗帜

有时候我们需要添加不同语言版本，而在GFM中可以像添加普通图片一样添加该国家/地区的国旗标志：

国家	语法	效果
Brazil	
Bulgaria	
China	
France	
Germany	
Italy	
Japan	
South-Korea	
Russia	
Spain	
Thailand	
Ukraine	
Vietnam	
Catalan	

diff语法

版本控制的系统中都少不了diff的功能，即展示一个文件内容的增加与删除。GFM中可以显示的展示diff效果。使用绿色表示新增，红色表示删除。

其语法与代码高亮类似，只是在三个反引号后面写diff，并且其内容中，以 + 开头表示新增，- 开头表示删除：

```diff
+ 新增内容
- 删除内容

效果：

+ 新增内容
- 删除内容

目录树

为了更直观的对项目结构进行解释，有时候需要在README等文件中插入目录树：

Project
|-- ContentStore
|   |-- de-DE
|   |   |-- art.mshc
|   |-- en-US
|       |-- art.mshc
|       |-- artnoloc.mshc
|-- IndexStore
    |-- de-DE
    |   |-- art.mshi
    |   |-- artnoloc.mshi
    |   |-- clientserver.mshi

复制以上代码就可以完成一棵目录树了:)

点击展开效果

在github上面闲逛时看到一些很动态的效果，比如"点击展开"这种效果，其语法是将内容用details包裹，然后将可点击内容用summary包裹：

<details>
<summary><b>show the qrcode image</b> (click to show)</summary>

![qrcode](./src/qrcode.jpg)

</details>

效果：

show the qrcode image (click to show)

当然，你可以发挥自己的想象力，将"点击展开效果"应用在其他地方，比如隐藏目录：

<details>
<summary><b>Expand to show Table of Contents</b> (click to show)</summary>
* Level 1
* Level 1
  * Level 2
  * Level2
    * Level 3
    * Level 3
* Level 1
</details>

Expand to show Table of Contents (click to show)

• Level 1
• Level 1
  • Level 2
  • Level2
    • Level 3
    • Level 3
• Level 1

GFM VS SM

下面对GFM和SM的区别进行一下总结：

• GFM二级标题自动带有下划线
• GFM在issue中通过#和数字自动链接到对应的issue（request也支持）（eg：#1）
• GFM自动识别链接，链接不用尖括号括起来也会被认为是链接（Email地址同样适用）。
• GFM实现代码语法高亮
• GFM自动@别人
• GFM自动引用，包括项目，用户名，issue等
• GFM支持上面介绍过的任务列表

语法

• 官方语法
• GitHub MakDown 语法
• PDF版本

Markdown编辑器

Windows 平台

• MarkdownPad
• MarkPad
• mdcharm

Linux 平台

• ReText

Mac 平台

• Mou
• DayOne

在线编辑器

• Draftin：功能强大，可发布到各种博客平台。
• Dillinger：实时预览，支持直接保存到Dropbox或是Github。
• Markable：实时预览，支持发布到Tumblr。
• Oak：不支持发布到任何地方，供在线随手记录东西使用。
• 简书：国产软件，看上去不错。

浏览器插件

• MaDe (Chrome)

Users

• GitHub
• 简书
• Stack Overflow
• Apollo
• Moodle
• Reddit
• ...

参考链接

• Markdown语法示例
• MarkDown书写规范
• Markdown 编辑器语法指南
• Markdown 基本语法
• README文件语法解读
• markdown-it
• GitHub 风格的 Markdown 语法

题外话

不同的Markdown解释器或工具对相应语法（扩展语法）的解释效果不尽相同，具体可参见工具的使用说明。 虽然有人想出面搞一个所谓的标准化的Markdown，没想到还惹怒了健在的创始人John Gruber。