Markdown 完全指南

概述

Markdown 是一种用于网络文本书写的轻量级标记语言，广泛用于个人 blog、github、wiki 中。其实浏览器并不能识别 Markdown 的语法，但许多 blog、wiki 平台以及 github 都内置了 Markdown 编辑器，编辑器会先把 Markdown 文本转换成 HTML 格式的网页，然后再把 HTML 网页交给浏览器来显示。除了上述的内置编辑器外，还有许多能解析 Markdown 语法的编写工具，这些工具一般都提供浏览器预览和导出成 HTML 或 PDF 文件的功能。

Markdown 的语法由一些符号定义，这些符号夹杂在文本中，用于控制文本的显示方式。比如两个星号可以给文字加粗**加粗**，这两个星号在 Markdown 编辑器处理后就变成了 HTML 中的<strong>加粗</strong>标签。相较于 Word 类型编辑器的“所见即所得”而言，Markdown 文件本身是纯文本，并没有格式，但通过 Markdown 语法符号能提供更加准确的 HTML 类型格式控制同时又没有 HTML 那么难以书写。

Markdown 的语法需要编辑器才能实现，因此编辑器可以按照自己的需求添加或者修改某个语法的含义。因此，基本上所有编辑器解析 Markdown 语法的方式都有些许差异，但大体上可以分成三类：

• Classic Markdown：最基础的 Markdown 语法，所有的编辑器都支持
• Extra Markdown：扩展的 Markdown 语法，增加了表格等元素，不一定都能支持
• Github Markdown：github 文档使用的 Markdown 语法，包含 Extra Markdown 的所有内容，还增加了代码高亮、emoji表情等语法，目前许多 blog 平台（cnblogs，csdn）都支持这种语法

本文主要介绍 Classic 和 Github 的语法，对于只有 Github 支持的语法会用上标\(^g\)注明，同时就在使用 Markdown 中经常遇到的问题给出解决方案。作者希望能在一篇文章中将 Markdown 使用中经常遇到的问题做全面总结，若有错漏，欢迎指正。

注：作者在编写此文的过程中发现 cnblogs 的 Markdown 编辑器有个别地方处理不符合标准，代码块和引用块的默认样式有点丑，并且不支持预览，请各位斟酌后使用。

语法

标题和段落

标题支持两种语法：底线格式和井号格式。标题会转换成 HTML 中的<h1><h2>等标签，这对于自动生成目录非常重要（Markdown 没有自动生成目录的语法，不过可以利用其他的方式）。

底线格式需要单独一行，使用至少两个=或-，只能处理两阶的标题。

标题1
===
标题2
---

井号格式使用 1～6 个的#，最多六阶标题。行尾可以添加任意个#号，并不会被当作标题的一部分。

# 标题1 #
## 标题2
###### 标题6 ##

段落开头不能使用空格或制表符缩进，连续的文本行会首位相连成为一个段落（cnblogs编辑器不会合成段落）。不同段落之间需要用一个或多个空行（空行可以包含空字符）分隔。如果想将连续的文本行解释为两个段落，在第一个文本上的末尾键入两个空格后再换行。在生成 HTML 时，段落开头的空格会被忽略或被解释为代码块等格式，段落之间的所有空行都会被忽略。

  行首空格、段间空行都被忽略。
连续文本行会被合成一段。（cnblogs编辑器仍然是两段）

可以在第一行最后加两个空格后换行
就可以分段了。

行首空格、段间空行都被忽略。

连续文本行会被合成一段。（cnblogs编辑器仍然是两段）

可以在第一行加两个空格后换行

就可以分段了。

链接和图片

链接用于跳转到其他页面，包含行内式和参考式两种样式，还可以使用简单的自动链接。跳转地址可以用/开头的相对路径引用本机资源。

行内式：链接文字和跳转地址写在一起。如：

[an example](http://www.cnblogs.com/zhuyuanhao/ "链接title")

an example

参考式：链接文字和跳转地址分开写，通过[id]标识联系起来。[id]标识可以包含字母、数字、空白和标点符号，但是并不区分大小写。跳转地址部分可以出现在文件的任意地方。

This is [an example][ID 2] reference-style link.

[id 2]: http://www.cnblogs.com/zhuyuanhao/ "可选title, 可以用单引号'、双引号"或括号()包着，也可以另起一行并缩进"
[iD 3]: <http://www.cnblogs.com/zhuyuanhao/>
	'跳转地址也可以用尖括号包起来'

隐式参考链接：使用空标识[]，在跳转地址处使用链接文字作为标识。

[Google][]

[Google]: http://google.com/ "Google Inc."

自动链接：对于网址和电子邮件信箱，只要是用尖括号包起来，Markdown 就会自动把它转成链接，链接文字和跳转地址相同。

<http://www.cnblogs.com/zhuyuanhao/>
<address@example.com>

http://www.cnblogs.com/zhuyuanhao/

address@example.com

图片用于在当前页面显示图片，也包含行内式和参考式，只需要在链接的样式前加一个惊叹号!，就会被识别为图片。可以使用相对路径引用本地的图片，也能使用 url 引用其他网站的图片。不过到目前为止，Markdown 还没有办法指定图片的宽高。

行内式：

![Alt text](/path/to/img.jpg "Optional title")

参考式：

![Alt text][id]

[id]: url/to/image  "Optional title attribute"

引用块

引用块使用右尖括号>标识，可以在每行都加上>，也可以只在段落的第一行加>。

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

> Donec sit amet nisl.
 Aliquam semper ipsum sit amet velit. Suspendisse
 id sem consectetuer libero luctus adipiscing.

可以使用多个>表示引用块的不同层级。

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

引用的区块内也可以使用其他的 Markdown 语法，包括标题、列表、代码块等。

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

代码

代码可以用行内代码或者代码块来表示。

行内代码使用一个或多个重音符号来表示代码区域，起始和结束的重音符号个数必须相同。

Use the `printf()` function.

Use the printf() function.

如果想在代码区域内插入k个重音符号，可以用k+1个重音符号来开启和结束代码区段。

There is a literal ```backtick (``)``` here.

There is a literal backtick (``) here.

如果在起始和结束端都插入空格，就可以在区域的一开始就插入重音符号。

A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

Classic 代码块使用每行缩进的 4 个空格或是 1 个制表符来表示。在转换成 HTML 时，每行行首的 4 个空格或 1 个制表符缩进会被移除，其余的空格或制表符会被保留。另外，一般在代码块中的 Markdown 语法符号不会被转换。

Here is an example of AppleScript:

    tell application "Foo"
        **beep**
    end tell

Here is an example of AppleScript:

tell application "Foo"
    **beep**
end tell

Github 代码块使用三个或以上重音符号(```)放在代码块的前一行和后一行。在前一行重音符的后面加上语言名称，可以按照该语言的语法对代码块内容高亮。如果要在代码块中显示三个重音符，用四个重音符来表示代码块起止即可。支持的编程语言参见the languages YAML file，如果要使用没有语法高亮的代码块，用plain标记。

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

列表

列表包括无序列表和有序列表两类。列表的每一项都使用标记 + 分隔（至少一个空格或制表符） + 段落的格式，段落的内容可以跨行，用空格缩进，还可以包含代码块、引用块等。如果在一个列表项里添加用空行隔开的多个段落，需要在每个段落开头添加至少两个空格。如果要表示多级列表，需要在下一级列表标记前加上至少两个空格或一个制表符，多级列表可以混用不同的标记（cnblogs的 Markdown 不支持多级列表）。

无序列表使用星号*、加号+或是减号-作为列表标记，标记不能混用，否则会视为不同的列表。

有序列表则使用数字和一个英文句点表示，数字的内容是任意的，并不会影响 HTML 显示的数字。有时不需要列表，但在段落开头的文字是数字加句点的格式，为了不被 Markdown 解析成列表，需要在句点前加上反斜线，如：2016\. Something Begin.

+ 无序列表项1
+ 无序列表项2
 + 下一级列表
   2. 再下一级列表1
   2. 再下一级列表2
- 不同标记视为不同列表
- 列表还可以
```c
# 包含代码块
int a = 10;
```
- 或者引用
> I have a dream!
- 以及多行或多段。
第二行

  第二段

2016\. Something Begin.

表格\(^g\)

表格只能用在Extra Markdown或Github Markdown中。用竖线|和连字符-表示，竖线用于分隔表格中的不同列，连字符用于分开表头和表格主体，连字符添加冒号:还可以控制单元格对齐方式。书写时，竖线没有对齐要求，行首行尾的竖线可以省略，表头下需要至少三个连字符分隔。

表格内容可以包含 Mardown 行内格式，不能添加引用、列表、多行文本，可以包含代码行，不能用代码块。若要书写竖线，需要用反斜线转义\|（cnblogs编辑器支持有问题）。

| 默认左对齐 | 左对齐 | 中对齐 | 右对齐 |
| ------    | :--- | :---: | ---: |
 头尾的竖线可以省略 | 对齐 | 对齐 | 对齐
| **加粗** | `int a;` | 竖线 \| | 链接[Google](www.google.com) |

默认左对齐	左对齐	中对齐	右对齐
头尾的竖线可以省略	对齐	对齐	对齐
加粗	int a;	竖线 | 链接Google

文字样式和转义符号

文字样式包括加粗、斜体、删除线。其中 Classic Markdown 不支持删除线。加粗用**或__表示，斜体用*或_表示，删除线用~~表示。如果样式符号两边都没有文字的话，会被当作普通符号，如：** 符号 **效果为 ** 符号 **

样式	语法	举例	效果
加粗	**或__	**文本**或 __文本__	文本或 文本
斜体	*或_	*文本*或 _文本_	文本或_文本_
删除线	~~	~~文本~~	文本
混合	将上述符号混合	**~~文本~~*混合* **效果	**文本混合 **效果

对于 Markdown 中的语法符号，前面加反斜线\即可显示符号本身。包括

\\ 反斜线
\` 重音号
\* 星号
\_ 下划线
\{\} \[\] \(\) 括号
\# 井号
\+ 加号
\- 减号
\. 句点
\! 惊叹号

\ 反斜线

` 重音号

* 星号

_ 下划线

{} [] () 括号

# 井号

+ 加号

- 减号

. 句点

! 惊叹号

分割线用三个以上的星号*、减号-或下划线_表示，符号之间可以用空格分开但行内不能有其他非空白符号。

***
- - -
_______

---

---

---

任务列表\(^{g\)和emoji表情\(}g\)

Github Markdown 支持任务列表样式和 emoji 表情符号。（cnblogs编辑器里，这两项的支持都不是很好）

任务列表需要在 Markdown 列表项的段落部分用[ ]开头，也可以用[x]开头表示一个已选择的任务项。

- [x] 学习 Markdown
- [ ] 使用 Markdown
  1. [ ] 写博客

emoji表情使用:EMOJICODE:的格式，详细的表情列表参见EMOJI CHEAT SHEET。

:man: :thumbsup: :sunny: :bug:

在 Github 平台还有两个特殊的功能：使用@user/team来通知用户或者用户组或使用#number引用某个 Issue 或者 Pull Request。这两个功能只在 Github 平台有效，这里就不详述了，可以参考mentioning-users-and-teams。

HTML 标签

Markdown 中可以直接书写大部分 HTML 标签。其中在 HTML 的区块类型标签<div>、<table>、<pre>、<p> 等内的，Markdown 语法会失效，在 HTML 行内型标签<span>、<cite>、<del> 等内，Markdown 语法仍然有效。需要注意的是，在 HTML 标签内，书写特殊字符 < 和 & 仍然需要用它们的替代形式 < 和 &表示。在 Markdown 中，也能用 < 和 & 的这种特殊形式。

This is <a href="http://cn.bing.com/images/search?q=markdown&amp;go=Submit+Query">Markdown</a>  regular paragraph.
1 < 3 & 5
2 &lt; 4 &amp; 6
<table border="1" bgcolor="yellowgreen">
    <tr>
        <td>**count** 1 </td>
	<td>**count** 2 &lt; 4 &amp; 6</td>
    </tr>
</table>
This is **<em>another regular** paragraph</em>.

This is Markdown regular paragraph.

1 < 3 & 5

2 < 4 & 6

**count** 1

**count** 2 < 4 & 6

This is **another regular** paragraph.

支持 Tex 公式

在 Markdown 中添加 Tex 公式有两种方式：请求外部服务器生成或者本地生成

外部服务器生成方式是发送 Tex 公式到外部服务器，然后服务器会将 Tex 公式的图片发送回来，这种方式不能处理复杂的 Tex 语法。使用 HTML <img>标签，将 Tex 公式写在 <img>标签的 url 链接的参数里。如：

Google Chart服务器

<img src="http://chart.googleapis.com/chart?cht=tx&chl=\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">

forkosh服务器

<img src="http://www.forkosh.com/mathtex.cgi? \Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">

本地生成方式将 Tex 解析脚本插入到 HTML 文件的<head>标签中，在 HTML 文件渲染的过程中生成 Tex 公式，当网页中 Tex 公式比较多时速度会变慢。推荐使用 MathJax 引擎来实现，通过将下列 JS 脚本嵌入到生成的 HTML 文件<head>标签中，就能解析 Tex 公式了。Markdown 文件不应包含 <script> 标签，一般是通过修改 Markdown 编辑器的设置来自动添加。

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

行间公式（$$Tex$$）：$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$

\[x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
\]

行内公式（$Tex$或\\(Tex\\)）：\\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\\)

\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\)

csdn 的 Markdown 编辑器默认支持 Tex 公式，cnblogs 需要在博客“选项”中选中“启用数学公式支持”，MarkdownPad2 需要在Tools > Options > Advanced > HTML Head Editor中添加 MathJax 引擎，在F6预览中显示 Tex 公式。

免费编辑器

书写 Markdown 离不开编辑器。这里罗列各个平台下的免费编辑器供参考

平台	编辑器
Windows	MarkdownPad2
Mac	Mou
Linux	ReText
线上编辑器	Dillinger.io、StackEdit
博客平台	cnblogs、csdn、简书
Chrome插件	Markdown Preview Plus

另外，Sublime、Vim都带有 Markdown 预览插件。

免费图床

Markdown 文件本身不能包含图片。因此，要发布带图片的 Markdown 文章，就需要先将图片存放在网络上，通过 url 地址引用图片：![desc](url)。博客平台一般会提供图片上传服务，这样就可以在博客中引用图片的 url ，但是转发到博客外部就不一定能访问。网络图床服务器中的图片能在所有地方访问，但也有网络失效或者服务器关闭的风险。

这里罗列几个比较好用的图床服务器

地址	说明
https://sm.ms/	国际图床，无注册、不限流量
Github	可以把图片上传到github上
https://portal.qiniu.com	国内云存储服务七牛云，需注册、有流量限制，但可以自己控制
http://yotuku.cn/	国内图床，无注册、不限流量

参考链接

Classsic Markdown：http://daringfireball.net/projects/markdown/syntax/

Classsic Markdown的翻译版：http://wowubuntu.com/markdown/

Extra Markdown：https://michelf.ca/projects/php-markdown/extra/

Github Markdown：https://help.github.com/categories/writing-on-github/

MathJax：https://www.mathjax.org/