块级元素

标题

Markdown 支持两种形式的标题, [Setext] [1] 和 [atx] [2].

Setext 样式的标题使用的等号来表示一级标题, 使用连字符表示二级标题. 例如:

This is an H1

=============

This is an H2

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

任意长度的 = 或 - 都是可以的.

Atx 样式的标题每行开头使用 1-6 井号, 对应 1-6 级标题. 例如:

# This is an H1

## This is an H2

###### This is an H6

块引用

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.

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, fringillain, laoreet vitae, risus.> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisseid sem consectetuer libero luctus adipiscing.

块引用可以嵌套 (例如, 块引用中包含块引用) , 只需添加额外层级的 > 即可:

> This isthefirstlevelofquoting.

>

> > This is nested blockquote.

>> Backtothefirstlevel.

块引用可以包含 Markdown 元素, 包括标题, 列表和代码块:

>## This is a header.

>

>1.Thisisthefirstlistitem.

>2.Thisisthesecondlistitem.

>

> Here'ssomeexample code:

>

>   returnshell_exec("echo $input | $markdown_script");

任何合适的文本编辑器都应该可以很方便的创建 email 样式的块引用. 例如, 用 BBEdit 就可以选取文本然后从 'Text' 菜单中选择 'Increase Quote Level'.

---

列表

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

无序列表使用星号, 加号, 和连字符 -- 这些符号是可互换的 -- 最为列表标记:

*  Red

*  Green

*  Blue

等价于:

+  Red

+  Green

+  Blue

以及:

-Red

-Green

-Blue

有序列表使用数字加句号:

1.  Bird
2.  McHale

3.  Parish

如果列表项中包含块注释 , 块注释标记 > 需要缩进:

* A list item with a blockquote:

    > This is a blockquote

    > inside a list item.

如果列表项中有代码块, 代码块需要 双倍 缩进-- 8 个空格或者两个水平制表符:

*  A listitemwithacode block:        

                <code goes here>

有时候无意中出发有序列表, 如下面这样的代码:

1986. Whatagreat season.

即使, 如果一行开头满足 number-period-space 模式. 可以通过转义点号来避免这种情况:

1986\. Whatagreat season.

代码块

预格式化的代码块用于输出编程语言和标记语言. 不同于普通段落, 代码块中的行会被原样呈现.  MarkDown 会用

<pre> 和 <code> 标签包围代码块

要在 Markdown 中插入代码块, 只需要将每一行都缩进 4 个空格或者 1 个水平制表符. 例如, 下面的输入:

This is a normal paragraph:

    This is a code block.

只有一级缩进 -- 4 个空格或者 1 个水平制表符 -- 会从代码块中的每一行中移除. 例如:

水平线

如果一行中只有三个以上的连字符, 星号, 或者下划线则会在该位置生成一个 <hr /> 标签. 星号和连字符之间的空格也是允许的. 下面的例子都会生成一条水平线:

* * 

*********

- - -

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

---

内联元素

链接

Markdown 支持两种链接形式: 内联 和 引用.

这两种形式下链接文本的定界符都是 [中括号].

要创建内联链接, 只需在链接文本的右括号后面紧接一对圆括号. 圆括号里面放所需的 URL 链接, 还可以放一个 可选 的链接标题, 标题要用引号包围. 例如:

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

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

将会生成:

如果是引用相同服务器下的本地资源, 还可以用相对路径:

See my [About](/about/) page for details.

引用类型的链接放在第二个中括号里, 括号里面放链接标签:

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

两个中括号之间可以有空格:

Thisis[anexample] [id]reference-stylelink.

接下来, 在文档中的任意位置, 你可以像下面那样定义链接标签, 需要单独占一行:

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

也就是:

    方括号中包含链接标识符 (可以用三个以上的空白符来添加缩进);

    跟着是冒号;

    跟着是一个以上的空白符和水平制表符;

    跟着是链接的 URL;

    跟着是可选的标题属性, 可以用单引号, 双引号, 或者圆括号包围.

以下三个链接的定义是等价的:

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

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

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

注意: Markdown.pl 1.0.1 有一个已知的问题就是不能用单引号来包围链接标题.

URL 可以用尖括号包围:

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

对于较长的 URL , 为了美观起见, 你可以另起一行放置链接标题, 需要在前面加额外的水平制表符或空格作为内间距:

[id]:http://example.com/longish/path/to/resource/here

        "Optional Title Here"

链接定义只存在于 Markdown 处理期间, 而不会在最终的 HTML 出现.

链接定义的名称可以包含字母, 数字, 空格, 和标点符号 -- 但它们 不是 大小写敏感的. 例如, 下面两个链接是等价的:

[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/

链接定义可以放在 Markdown 文档的任意位置. 一般倾向于将它们直接放在引用位置下面, 当然, 也可以像底部注释那样, 将它们都放在文档底部.

下面是一个引用链接实例:

I get 10timesmoretrafficfrom

[Google] [1]thanfrom[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"

引用连接的意义不在于更容易书写, 而在于使得文档更易于阅读. 比较上面两个例子: 使用引用链接的段落只有 81 个字符; 使用内联链接的段落有 176 个字符; 而原始的 HTML 有 234 个字符. 在原始的 HTML 中, 标记比文本还多.

使用 Markdown 的引用链接, 源码更接近与最终的输出, 就像浏览器中呈现的样子. 通过把标记元数据移出段落, 你可以不用打断行文而直接添加链接.

强调

Markdown 将星号 (*) 和下划线 (_) 作为强调标记. 用 * 或者 _ 包裹的文本将会用 HTML  标签包裹; 双 * 或者 _ 将会用 HTML  标签包裹. 例如, 下面的输入:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

会输出:

single asteriskssingle 

underscores

double asterisks

double underscores

两种形式可以任意选择, 但是同一片段的开关标记必须一致.

强调可以用在单词中:

un*frigging*believable

但是如果 * 或者 _ 两边都有空格, 则会被视为星号和下划线的字面量.

要使用星号和下划线字面量, 需要进行转义, 以区别于强调:

\*thistextissurroundedbyliteral asterisks\*

代码

要输出一个代码片段, 需要使用重音符号 (`). 不同于预格式的代码块, 代码片段只是在普通段落中标识出代码. 例如:

Usethe `printf()` function.

会生成:

Use theprintf()function.

要在代码片段中包含字面量的重音符号, 可以使用多个重音符号作为起始和结束标记:

``There isaliteral backtick (`)here.``

会生成:

There is a literal backtick (`) here.

包含代码片段的重音符号可以包含空格 -- 起始标记后一个, 结束标记前一个. 这使你可以在代码片段开始和结束位置使用重音符号的字面量:

A single backtickinacodespan: `` ` ``

A backtick-delimited stringinacodespan: `` `foo` ``

图片

通常, 要用 "原生" 的语法在纯文本格式中插入图片是很困难的.

Markdown 使用了类似链接的语法来插入图片, 包含两种形式: 内联 和 引用.

内联图片语法如下:



也就是:

    一个感叹号: !;

    紧跟着一对方括号, 包含了图片的 alt 属性;

    紧跟着一对圆括号, 包含了图片的 URL 或者路径, 以及一个可选的用单引号或双引号包裹的 title 属性.

引用图片语法如下:

    ![Alt text][id]

"id" 是图片引用的名称. 图片引用使用链接定义的相同语法:

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