Markdown 使用方法摘要-原创手记-慕课网

此文是阅读 Markdown 语法说明后的一些相关摘要，并根据实际情况配备了合适的例子进行相关演示说明，希望对各位读者能有所帮助

本文绝大部分内容摘自如下网站：

Markdown 中文网 & Markdown 英文网

以下部分为本篇内容正文（ 注意： 本文全部采用 Markdown 进行排版）

宗旨

Markdown 的目标是实现[易读易写]。一份使用 Markdown 格式撰写的文件可以直接以纯文本发布，并且看起来不会像是由许多标签或是格式指令所构成。

兼容HTML

Markdown 语法目标：成为一种适用于网络的书写语言。

Markdown 并不想要取代HTML，也没有要和它相近，它的语法种类很少，只对应HTML标记的一部分。Markdown 的构想不是要使得HTML文档更容易书写，其理念是希望能让文档更容易阅读、书写和随意修改。HTML是一种发布的格式，Markdown是一种书写的格式。所以， Markdown 的格式语法只涵盖纯文本可以涵盖的范围。

不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用HTML攥写。不需要额外标注这是 HTML 或者 Markdown ；只要直接加标签就可以。

要制约的只有一些 HTML 区块元素——比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其内容区隔开，还要求它们的开始标签和结尾标签不能使用制表符或空格来缩进。 Markdown 的生成器有足够智能，不会在HTML 区块标签外加上不必要的 <p> 标签。

举例说明（在 Markdown 文件里加上一段 HTML 表格）：

效果一：

这是一个普通段落（开始）：

这是一个普通段落（结束）。

效果二：

这是HTML标记语言（ table 进行了制表符缩进）

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

这是HTML标记语言结尾。

注意： 在 HTML 区块标签间的 Markdown 格式语法不会被处理。比如，你在HTML 区块内使用 Markdown 样式的强调会没有效果。

举例说明：

情况一：处于 HTML 区块标签中

<table>
    <tr>
        <td>*Foo*</td>
    </tr>
</table>

情况二：不处于 HTML 区块标签中

HTML 的区段（行内）标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题中随意使用。依据个人习惯，甚至可以不用 Markdown 格式，而直接采用 HTML 标签来格式化。

举例说明：

使用 <span> 标签：

<span>Span的例子</span>

<cite>Cite的例子</cite>

<del>Del的例子</del>

举例说明：如果比较喜欢 HTML 的 <a> 或 <img> 标签，可以直接使用这些标签，而不用 Markdown 提供的链接或是图像标签语法。

<a href="Markdown" target="_blank" rel="nofollow">http://www.markdown.cn">Markdown</a>

和处于 HTML 区块标签间不同，Markdown 语法在 HTML 区段标签间是有效的。

举例说明：

特殊字符自动转换

在 HTML 文件中，有两个字符需要特殊处理： < 和 & 。 < 符号用于起始标签， & 符号则用于标记 HTML 实体，如果你只是想要显示这些字符的原型，你必须要使用实体的形式，像是 < 和 & 。

& 字符尤其让网络文档编写者受折磨，如果你打 [AT&T]，你必须要写成 [AT&am;T]。而网址中的 & 字符也要转换。比如你要链接到：

http://images.google.com/images?num=30&q=larry+bird

你必须要写成：

http://images.google.com/images?num=30&amp;q=larry+bird

才能放到链接标签的 href 属性里。不用说也知道这很容易忽略，这也可能是 HTML 标准检验所检查到的错误中，数量最多的。

Markdown 让你可以自然的书写字符，需要转换的由它来处理就可以。如果你使用的 & 字符是 HTML 字符实体的一部分，它会保留原状，否则它会被转换为 & 。

所以如果你需要在文档中插入一个版权符号©，你可以这样写：

©

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

AT&T

Markdown 就会将它转为：
AT&T

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

4 < 5

Markdown 将会把它转换为：

4 < 5

需要注意的是，code 范围内，不论是行内还是区块，< 和 & 两个符号都一定会被转换成 HTML 实体。

区块元素

段落和换行
一个Markdown段落是由一个或多个连续的文本或组成，它的前后要有要给以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行）。普通段落不应该使用空格或制表符来缩进。

举例说明（请根据两种情况说明，对比其产生的不同效果）：

情况一：下面两段文字，第一段文字结束后没有空开一行，而是直接输入第二段文字。

第一段文字：一个Markdown段落是由一个或多个连续的文本或组成，它的前后要有一个以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行）。普通段落不应该使用空格或制表符来缩进。
第二段文字：一个Markdown段落是由一个或多个连续的文本或组成，它的前后要有一个以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行）。普通段落不应该使用空格或制表符来缩进。

情况二：下面两段文字，第一段文件结束后空开一行，再次输入第二段文字。

第一段文字：一个Markdown段落是由一个或多个连续的文本或组成，它的前后要有要给以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行）。普通段落不应该使用空格或制表符来缩进。

第二段文字：一个Markdown段落是由一个或多个连续的文本或组成，它的前后要有要给以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行）。普通段落不应该使用空格或制表符来缩进。

Markdown允许段落内强迫换行（插入换行符），如果你确实想要依赖 Markdown 来插入 <br / > 标签的话，在插入处先按下两个以上的空格然后回车。

需要多费点事（多加空格）来产生 <br /> ，但是简单地每个换行都转换为 <br /> 的方法在 Markdown 中并不适合，Markdown 中 email 式的区块引用和多段落的列表在使用换行来排版的时候，不但更好用，还更方便阅读。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

类 Setext 形式是用底线的形式，利用 = （最高阶标题）和 - （第二阶标题），例如：

This is an H1

This is an H2

任何数量的 = 和 - 都可以有效果。

类 Atx 形式则是在行首插入 1 到 6 个 #，对应到标题 1 到 6 阶，例如：

这是 H1

这是 H2

这是 H3

这是 H4

这是 H5

这是 H6

你可以选择性的[闭合]类atx样式的标题，只是纯粹的为了美观，若是觉得看起来比较舒适，你就可以在行尾加上 #，而行尾的 # 数量也不用和开头一样（行首的井号数量决定标题的阶数）

这是 H1

这是 H2

这是 H3

区块引用

Markdown 标记区块引用是使用类似 email 中 > 的引用方式。在文字前面加上 > ：

这是文字引用。

引用也可以嵌套使用，只要根据层次加上不同数量的 > ：

区块也可以嵌套使用

比如现在你看到的效果

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

这是第一个标题

这是第一行列表项

这是第二行列表项

给出一些例子代码：

return shell_exec("echo $input | $markdown_script");

列表

Markdown 支持有序列表和无序列表：

Red
Green
Blue

等同于

Red
Green
Blue

也等同于

Red
Green
Blue

有序列表则使用数字接着一个英文句点：

Bird
McHale
Parish

很重要的一点是，你在列表标记上使用的数字并不会影响到输出的HTMl结果，上面的列表产生的HTML标记为：

<ol>
    <li>Bird</li>
    <li>McHale</li>
    <li>parish</li>
</ol>

如果你的列表标记写成：

1. Bird
1. McHale
8. Parish

其显示结果也会为：

Bird
McHale
Parish

如果你比较懒，你可以完全不用在意你书写数字的正确性，如果你有强迫证，你也可以让其书写数字和显示数字一样。

如果列表项目间用空行分开，在输出 HTML 时 Markdown 就会将项目内容用 <p> 标签包起来，举例来说：

Bird
Magic

会被转换为：

<ul>
    <li>Bird</li>
    <li>Magic</li>
</ul>

但是这个：

Bird
Magic

会被转换为：

<ul>
    <li><p>Bird</p></li>
    <li><p>Magic</p></li>
</ul>

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

A list item with a blockquote:

This is a blockquote
inside a list item

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

一列表项包含一个列表区块
```
<div>
    <table></table>
</div>
```

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

1986. What a great season.

运行效果如下：

What a great season.

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

1986. What a great season.

代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 标签来把代码区块包起来。

要在 Markdown 中建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以。例如，下面的输入：

这是一个普通段落：

这是一个代码区块。

Markdown 会转换成：

<p>这是一个普通段落：</p>

<pre><code>这是一个代码区块。</code></pre>

这个每行一阶的缩进（4个空格或是1个制表符），都会被移除，例如：

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell

会被转换为：
<p>Here is an example of AppleScript:</p>
<pre><code>tell application
"Foo"
end tell
</code></pre>

一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

在代码区块里面，&、< 和 >会自动转成 HTML 实体，这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码，只需要复制贴上，再加上缩进就可以了，剩下的 Markdown 都会帮你处理，例如：

<div class="footer">
    © 2004 Foo Corporation
</div>

会被转换为：

<pre><code><div class="footer">
    ©2004 Foo Corporation
</div>
</code></pre>

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

分隔线

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

* * *

***

*****

- - -

-----------------

区段元素

链接

Markdown 支持两种形式的链接语法：行内式和参考式两种形式。

不管是哪一种，链接文字都是用[方括号]来标记。

要建立一个行内式的链接，只要在方括号后面紧接着圆括号并插入网址链接即可，如果你还想要加上链接的title文字，只要在网址后面，用双引号把title文字包起来即可，例如：

This is an example inline link.

会产生：

<p>This is <a href="http://example.com/" title="title">an example</a> inline link.</p>

如果你是要链接到同样主机的资源，你一块使用相对路径：

See my about page for details.

参考式的链接式在链接文字的括号后面再接上另一个方括号，而在第二个方括号里面要填入用以辨识链接的标记：

This is an example reference-style link.

你也可以选择性地在两个方括号中间加上一个空格：

This is an example reference-style link.

接着，在文件的任意位置，把这个标记的链接内容定义出来：

注意：起作用的标记链接不会显示出来给你看到

[id]: http://example.com/ "Optional Title Here"

链接内容定义的形式为：

方括号（前面可以选择性地加上至多三个空格来缩进），里面输入链接文字
接着一个冒号
接着一个以上的空格或制表符
接着链接的网址
选择性地接着title内容，可以用单引号、双引号或是括弧包着

下面这三种链接的定义是相同的：

[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Option Title Here'
[foo]: http://example.com/ (Optional Title Here)

网址定义只有在产生链接的时候用到，并不会直接出现在文件之中。

链接辨别标签可以有字母、数字、空白和标点符号，但是并不区分大小写，因此下面两个链接是一样的：
[link text][a]
[link text][A]

隐式链接标记功能让你可以省略指定链接标记，这种情况下，链接标记会视为等同于链接文字，要用隐式链接标记只要在链接文字后面加上一个空的方括号，如果你要让“Google”链接到google.com，你可以简化为：

[Google][]

然后定义链接内容：

[Google]: http:/google.com/

由于链接文字可能包含空白，所以这种简化型的标记内也许包含多个单词：

Visit [Daring Fireball][] for more information.

然后接着定义链接：

[Daring Fireball]: http://daringfireball.net/

链接的定义可以放在文件中的任何位置，比如链接出现的段落后面或者统一放在文章结尾，就像尾注一样。

下面是一个参考式链接的范例：

I get 10 times more traffic from [Google] [1] than from [Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google
[2]: http://search.yahoo.com/   "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"

如果改成用链接名称的方式写：

I got 10 times more traffic from [Google][] than from [Yahoo][] or [MSN][].
[google]: http://google.com/    "Google"
[yahoo]: http://search.yahoo.com/    "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"

上面两种写法产生的HTML代码是一样的，可以达到同样的效果。

下面是用行内式写的同样一段内容的Markdown文件，提供作为比较之用：

I get 10 times more traffic from [Google](http://google.com/ "Google") than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or [MSN](http://search.msn.com/ "MSN Search").

参考式的链接起始重点不在于它比较好写，而是它比较好读，上面的示例，使用参考式的文章本身只有81个字符，但是用行内式却增加到了176个字符，用纯 HTML 格式来写，还会更多。

强调

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

*single asterisks*

single asterisks

_single undersores_

sing undersores

**double asterisks**

double asterisks

__double asterisks__

double asterisks

强调也可以直接插在文字中间：

un*frigging*believable

unfriggingbelievable

如果你的 * 和 _ 两边都有空白的话，它们就会被当成普通的符号。

un frigging believable

如果要在文字前后直接插入普通的星号或底线，你可以用反斜线：

\*this text is surrounded by literal asterisks\*

*this text is surrounded by literal asterisks*

代码

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

use the `pringf()` function.

use the printf() function.

会产生：

<p>Use the <code>printf()</code> function.</p>

如果要在代码区段内插入反引号，你可以用多个反引号来开启和结束代码区段：

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

There is a literal backtick (`) here.

这段语法会产生：

<p><code>There is a literal backtick (`) here.</code></p>

图片

要在纯文字应用中设计一个语法来插入图片是有一定难度的。

Markdown 使用一种和链接很相似的语法来标记图片，同样也允许两种样式：行内式和参考式。

行内式的语法看起来像是：

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

Alt

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

Alt

详细叙述如下：

一个惊叹号
接着一个方括号，里面放上图片的替代文字
接着一个普通括号，里面放上图片的网址，最后还可以用引号包住并加上选择性的 'title'文字。

参考式的图片语法如下：

![Alt text][id]

Alt

id 是图片参考的名称，图片参考的定义方式则和连接参考一样：

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

到目前为止，Markdown 还没有办法指定图片的宽和高，如果你需要的话，你可以使用普通的 <img> 标签。

其他

反斜杠

Markdown 可以利用反斜杠来插入一些语法中有其它意义的符号，例如：如果你想要用星号加在文字旁边的方式来做出强调效果（但不用 <em> 标签），你可以在星号的前面加上反斜杠：

\*literal asterisks\*

*literal asterisks*

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

\ 反斜线

` 反引号

* 星号

_ 底线

{} 花括号

[] 方括号

() 圆括号

# 井号

+ 加号

- 减号

. 英文句点

! 惊叹号

自动链接

Markdown 支持以比较简短的自动给链接形式来处理网址和电子邮件信箱，只要用方括号包起来， Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样，例如：

<http://example.com/>

http://example.com/

Markdown 会转为：

<a href="http://example.com/">http://example.com/</a>

邮件的自动链接也很类似，只是 Markdown 会先做一个编码转换的过程，把文字字符转成16进位码的 HTML 实体，这样的格式可以糊弄一些不好的邮件收集机器人，例如：

<address@example.com>

address@example.com

Markdown 会转成：

<a href="mailto:address@example.com">address@example.com</a>

在浏览器里面，这段字串（其实是<a href="mailto:address@example.com">address@example.com</a>）会变成一个可以点击的[address@example.com]链接。