Markdown语法

Markdown语法

概述

原则

直接写HTML

特殊字符的自动转换

块元素

段落和换行

标题

引文

列表

代码块

水平分隔线

行元素

链接

强调

代码

图片

其它

逃逸字符

自动链接

概述

原则

Markdown的原则是尽可能地易读和易写。

易读尤其重要。用Markdown写的文件，应该是拿来就能“读”的纯文本，应该让 人感觉不到各类标签和格式指令的存在。Markdown的语法受很多类似工具的影响 ，包括Setext、atx、Textile、reStructuredText、Grutatext和EtText，但最大的 启发还是来自于纯文本的email格式。

所以，Markdown的语法完全由标点符号构成，这些标点符号都是经过认真挑选的 ，使得它们看起来就是那个意思。比如，星号看起来就像是*强调*。列表看起来就 像是列表。引文看起来就像是引文，当然前提是你知道email的引文是怎么回事。

直接写HTML

Markdown语法的目的只有一个：编写web内容。

但Markdown不打算取代HTML，甚至都不模仿它。Markdown的语法很简单，只 对应很少的几个HTML标签。我并不是要创造一个语法来简化HTML标签的使用。在 我看来，HTML标签已经很容易使用了。Markdown是想提供一种简单方式来阅读、 编写和编辑我们的随笔。HTML是用于发表的格式；Markdown是用于创作的格式。 所以，Markdown只会解决那些能够用纯文本解决的问题。

对于用Markdown解决不了的问题，你就直接用HTML好了。不需要特殊标记在 Markdown和HTML之间进行切换；想用直接用。

但对于块级HTML元素来说还是有一个限制，比如

<div>

、

<table>

、

<pre>

、

<p>

等，这些HTML必须用空白行和其他内容分来，而且开始标签和结束标签要独 占一行，并且不能有缩进。Markdown知道这是HTML，是不会用

<p>

再包一层的。

例如，可以这样插入一个HTML table：

This is a regular paragraph.

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

This is another regular paragraph.

需要注意的是，块级HTML元素内是不能使用Markdown语法的。例如，你不能在

<div>

内用*强调*表示强调。

行级HTML元素，比如

<span>

、

<cite>

、

<del>

等，可以随便用在Markdown的段落、列表项和标题中。如果你愿意的话，你可以直接使用HTML的

<a>

和

<img>

而不是Markdown的链接和图片语法，没有关系。

和块级HTML元素不一样，在行级HTML元素中是可以使用Markdown语法的。

特殊字符的自动转换

在HTML中，有两个特殊字符需要特殊处理：

<

和

&

。前者用于标识HTML标签的开始；后者用于标识一个HTML实体。如果你想要这两个字符的本来含义就需要将其转换为对应的HTML实体：

<

和

&

。

与号（&）尤其折磨人。如果你想写'

AT&T

'，你就必须写成'

AT&T

'。URL中与号（&）也很多。于是，如果你想写：

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

你就必须在href属性中写成：

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

Markdown允许你很自然地使用这些字符，会帮你完成这些转换。如果你把&用在一个HTML实体中，Markdown就不会转换；不然就会将其装换为&。

所以，如果你想使用版权符号，你可以写：

©

Markdown会让其保持原样。但是如果你写：

AT&T

Markdown就会将其转换为：

AT&T

同样的道理，如果你把<用于标签，Markdown会让其保持原样。但是如果你写：

4 < 5

Markdown会将其转换为：

4 < 5

最后，在Markdown的code语法中的<和&是始终都会转换的。这也使得Markdown很容易编写HTML相关的内容。

块元素

段落和换行

若干连续的行构成一个段落，段落之间用空白行分开。（空白行指的是空行，或者只包含空白符的行）一个正常的段落不应该有缩进。

Markdown不会下行尾添加

<br />

标签。如果你想添加

<br />

，就需要先打两个或以上的空格，在打回车。

标题

Markdown支持两种风格的标题：Setext和atx。

Setext风格把等号（=）和连字符（-）当下划线用，分别表示

<h1>

和

<h2>

。例如：

This is an H1
=============

This is an H2
-------------

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

atx风格在行首用1-6个井号，表示相应的HTML标题级别。例如：

# This is an H1

## This is an H2

###### This is an H6

你也可以对称地使用井号。这纯粹是为了好看，如果你认为好看的话。两边的井号数目甚至都可以不一样。（头部的井号数目才决定标题级别）：

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

引文

Markdown把email风格的>符号用于引文。如果你熟悉email的引文方式，你就知道如何在Markdown中使用引文了，两者是一样的。如果你给每一行都加上>，会好看一点：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

如果你不想费事，可以只在段落的第一行加>：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> 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");

很多文本编辑器都支持email风格的引文。例如BBEdit，你可以选择一段文本，然后增加其引用级别。

列表

Markdown支持有序号和无序号的列表。

无序号列表用星号、加号和连字符作为列表标记：

*   Red
*   Green
*   Blue

和

+   Red
+   Green
+   Blue

和

-   Red
-   Green
-   Blue

是等价的。

有序号的列表用数字加点号：

1.  Bird
2.  McHale
3.  Parish

你可以写成：

Bird

McHale

Parish

甚至：

Bird

McHale

Parish

你得到的结果是一样的。也就是说你可以让Markdown中序号和HTML结果中序号保持一致；如果你不想费事，随便给个数字也是可以的。

如果你想随便给个数字，最好还是从1开始，这是为了方便以后的扩展。

列表标记可以靠最左边，也可以空1-3个空格。列表标记后面可以有1个或多个空格。

想要列表好看一点的话，你把列表项缩进对齐：

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

如果你不想费事，可以直接这样：

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

列表项之间的空白行可以让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>

列表项可以有多个段落构成。每个段落必须4个空格或1个跳格进行缩进。

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

Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

同样的，如果你不想每行都缩进的话，可以这样：

*   This is a list item with two paragraphs.

This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

如果想在列表项中使用引文的话，引文也是需要缩进的：

*   A list item with a blockquote:

> This is a blockquote
> inside a list item.

如果想在列表项中使用代码块的话，也是需要缩进的，也就是代码块缩进了两次（8个空格或2个跳格）：

*   A list item with a code block:

<code goes here>

需要注意的是有可能会不小心写一个列表标记：

What a great season.

这种情况下你就需要用反斜杠对点号进行逃逸。

代码块

编程语言或标记语言的代码一般都是有格式的。Markdown将代码块放在

<pre>

和

<code>

中。

创建一个代码块很简单，把每一行用4个空格或1个跳格缩进就可以了。

This is a normal paragraph:

This is a code block.

HTML结果是：

<p>This is a normal paragraph:</p>

<pre><code>This is a code block.
</code></pre>

Markdown会删除一个级别的缩进，例如：

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"
beep
end tell</code></pre>

水平分隔线

你可以用3个或以上的星号、连字符和下划线创建水平分隔线

<hr />

。其间可以掺入空格。下面这些都会生成水平分隔线：

* * *

***

*****

- - -

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

行元素

链接

Markdown支持两种风格的链接：inline和reference。

在两种风格中，链接文本都需要用方括号（[ ]）括起来。

要创建inline风格的链接的话，需要在方括号后面紧跟一对圆括号。然后在圆括号中放入URL，URL后面跟一个标题属性，标题属性要用双引号括起来。标题属性不是必须的。例如：

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

会生成：

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

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

reference风格在方括号后面再跟一对方括号，里面放链接名：

This is [an example][id] reference-style link.

两对方括号之间是可以有空格的：

This is [an example] [id] reference-style link.

然后，在文件中的任何一个位置，你可以定义这个链接：

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

也就是：

包含链接名的方括号（可以用1-3个空格进行缩进）

后面跟冒号

然后是一个或多个空白符

然后是URL

然后是标题（不是必须的），用单引号、双引号或圆括号括起来

下面三者是等价的：

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

其中URL还可以用尖括号括起来：

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

对于较长的URL你还可以考虑把标题属性放在第二行，并用空白符缩进：

[id]: http://example.com/longish/path/to/resource/here "Optional Title Here"

这些链接定义处理完了会被剔除，不会出现在HTML结果中。

链接名可以包含字母、数字、空格和标点符号，而且是大小写不敏感的。例如：

[link text][a]
[link text][A]

是等价的。

隐式链接名是允许你把链接文本当做链接名。直接用一对空的方括号就行了，例如，你可以写：

[Google][]

然后定义：

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

因为链接名可以包含空格，这样也是可以的：

Visit [Daring Fireball][] for more information.

然后定义：

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

链接定义可以下载Markdown文件的任何位置。我倾向于把它们跟在相关段落后面，如果你喜欢，可以放在文件的最后，这样看起来有点像注脚。

这里是一个实际的例子：

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 get 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"

两者都会生成：

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

作为比较，如果用inline风格的话就会是这样：

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").

reference风格的关键是易读而不是易写。

强调

Markdown用星号（*）和下划线（_）标示需要强调的文本。1个表示

<em>

，2个表示

<strong>

。例如：

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

会生成：

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

强调也能用在一个词的中间，例如：

un*frigging*believable

如果*和_的两边有空格，它们就是普通字符。

也可以用反斜杠进行逃逸处理：

\*this text is surrounded by literal asterisks\*

代码

要标示一段代码，就用反单引号（`）将其括起来。例如：

Use the `printf()` function.

会生成：

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

如果代码中带有反单引号，就用2个反单引号将其括起来。例如：

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

会生成：

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

代码段的头部和尾部可以有一个空格，使得可以在代码段的头部和尾部使用反单引号：

A single backtick in a code span: `` ` ``

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

会生成：

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

图片

不可否认，很难把图片放入纯文本中。

Markdown模仿链接设计了图片的语法，也有两种风格：inline和reference。

inline风格看起来像：

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

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

也就是：

一个感叹号（!）

后面跟一对方括号（[ ]），里面放alt属性

后面跟一对圆括号（( )），里面放URL，URL后面是title属性，用单引号或双引号括起来；title属性不是必须的

reference风格看起来像这样：

![Alt text][id]

然后id的定义语法和链接是一样的：

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

现在还不能指定图片的尺寸，如果真的需要的话，你就直接使用

<img>

吧。

其它

逃逸字符

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

自动链接

Markdown为URL和email提供一种自动链接方式，前提是你希望把链接内容作为链接文本显示：直接把URL或email放入一对尖括号（< >）中。例如：

<http://example.com/>

会生成：

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

至于email，Markdown会稍微做点变换，希望可以防止email收割机器人（实际上只能对付一部分简单的）。例如：

<address@example.com>

会生成：

<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>