Markdown语法

Markdown语法

概述

Markdown 的目标是实现「易读易写」。具有很强的可读性，同时语法简单易学。

兼容 HTML

Markdown兼容HTML，不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown；只要直接加标签就可以了。
HTML 区块标签间的 Markdown 格式语法将不会被处理。比如，你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。（HTML 区块元素――比如 <div>、<table>、<pre>、<p> 等标签）

Markdown 语法在 HTML 区段标签间是有效的。HTML 的区段（行内）标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯，甚至可以不用 Markdown 格式，而直接采用 HTML 标签来格式化。举例说明：如果比较喜欢 HTML 的 <a> 或 <img> 标签，可以直接使用这些标签，而不用 Markdown 提供的链接或是图像标签语法。

特殊字符自动转换

Markdown 让你可以自然地书写字符，需要转换的由它来处理好了。如果你使用的 & 字符是 HTML 字符实体的一部分，它会保留原状，否则它会被转换成 &amp;。
所以你如果要在文档中插入一个版权符号 ©，你可以这样写：

©

Markdown 会保留它不动。而若你写：

AT&T

Markdown 就会将它转为：

AT&T

类似的状况也会发生在 < 符号上，因为 Markdown 兼容HTML，如果你是把 < 符号作为 HTML 标签的定界符使用，那 Markdown 也不会对它做任何转换，但是如果你写：

4 < 5

Markdown 将会把它转换为：

4 < 5

因此在很大程度上，你可以很容易地用 Markdown 写 HTML的代码（和 HTML 相对而言， HTML 语法中，你要把所有的 < 和 & 都转换为 HTML 实体，才能在 HTML 文件里面写出 HTML 代码。）

---

区块元素

段落和换行

在Markdown中，普通段落不该用空格或制表符来缩进。普通文本的首段缩进在Markdown中是无法实现的，段间的缩进我们可以用4个空格或者1个Tab进行缩进。
Markdown 允许段落内的强迫换行，如今大部分支持Markdown的编辑器都可直接通过回车键或插入换行符来实现换行。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式，其中类atx形式是我们最常用的。
类 Setext 形式是用底线的形式，利用 = （最高阶标题）和 - （第二阶标题），例如：

This is an H1
=============
This is an H2
-------------

任何数量的 = 和 - 都可以有效果。
类 Atx 形式则是在行首插入 1 到 6 个 # ，对应到标题 1 到 6 阶，例如：

# 这是 H1
## 这是 H2
###### 这是 H6

区块引用 Blockquotes

Markdown 标记区块引用是使用> 来实现的。在每行的最前面加上 > ：

>你真好看! 
>
>谢谢，你也很好看！

效果如下：

你真好看！

谢谢，你也很好看！

ps：Markdown 也允许你偷懒只在整个段落的第一行最前面加上 >
区块引用可以嵌套（例如：引用内的引用），只要根据层次加上不同数量的 > ：

>第一层
>
> > 第二层
>
>第一层

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

> ## 这是一个标题。
> 
> 1.   这是第一行列表项。
> 2.   这是第二行列表项。
> 
> 给出一些例子代码：
> 
>     return shell_exec("echo $input | $markdown_script");

列表

Markdown 支持有序列表和无序列表。
无序列表使用星号 *  、加号 + 或是减号 - 作为列表标记，注意中间要加一个空格：

* Red
* Green
* Blue

等同于：

+ Red
+ Green
+ Blue

也等同于：

- Red
- Green
- Blue

效果都为：

• Red
• Green
• Blue

有序列表则使用数字接着一个英文句点，英文句点后需要加一个空格：

1. Bird
2. McHale
3. Parish

效果为：

1. Bird
2. McHale
3. Parish

如果要在列表项目内放进引用，那 > 就需要缩进：

*   A list item with a blockquote:
    > This is a blockquote
    > inside a list item.

如果要放代码区块的话，该区块就需要缩进两次，也就是 8 个空格或是 2 个制表符：

*   一列表项包含一个列表区块：
        <代码写在这>

当然，项目列表很可能会不小心产生，像是下面这样的写法：

1986. What a great season.

换句话说，也就是在行首出现数字-句点-空白，要避免这样的状况，你可以在句点前面加上反斜杠。

1986\. What a great season.

代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 标签来把代码区块包起来。
要在 Markdown 中建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以，例如，下面的输入：

这是一个普通段落：
    这是一个代码区块。

Markdown 会转换成：

<p>这是一个普通段落：</p>
<pre><code>这是一个代码区块。
</code></pre>

代码区块中，一般的 Markdown 语法不会被转换，像是星号便只是星号，这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

分隔线

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线：

* * *
***
*****
- - -
---------------------------------------

---

区段元素

链接

Markdown要插入一个链接只要在方块括号后面紧接着圆括号并插入网址链接即可，如果你还想要加上链接的 title 文字，只要在网址后面，用双引号把 title 文字包起来即可，或者直接在方框中输入title例如：

[百度](http:/baidu.com)

效果为：百度

强调

Markdown 使用星号（*）和底线（_）作为标记字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围，用两个 * 或 _ 包起来的话，则会被转成 <strong>，例如：

*你是个好人*
_你是个好人_
**你是个好人**
__你是个好人__

但是如果你的 * 和 _ 两边都有空白的话，它们就只会被当成普通的符号。
如果要在文字前后直接插入普通的星号或底线，你可以用反斜线。

代码

如果要标记一小段行内代码，你可以用反引号把它包起来，例如：

Use the `printf()` function.

效果如下：Use the printf() function.
如果要插入代码块，可用三个反引号加插入代码的语言再加一个空格来实现。
```java 

图片

Markdown 使用一种和链接很相似的语法来标记图片。

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

反斜杠

Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号来作为普通符号使用。例如：我们想打出一个 * 号来作为乘号时可以在 * 前加上一个 \ ，这样 * 就不会产生语法的特殊意义 。

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号：

部分其他编辑器版本可能出现的功能

删除线

使用两个 ~ 将要划删除线的语句包住，实现删除线功能，如：删除线

高亮

使用两个 = 将要高亮的语句包住，实现高亮功能功，如：高亮

下标

使用一个 ~ 将要下标的语句包住，实现下标功能，如：H<sub>2</sub>O 下标

上标

使用一个 ^ 将要下标的语句包住，实现下标功能，如：2<sup>10</sup> 上标

待办列表

- [ ] Incomplete item
- [x] Complete item

脚注

Some text with a footnote.[^1]
[^1]: The footnote.

表格

| Column 1 | Column 2      |
|:--------:| -------------:|
| centered | right-aligned |

效果如下：

Column 1	Column 2
centered	right-aligned