markdown语法备忘录

区块元素

段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成，它的前后要有一个以上的空行。一般的段落不应该用空格和制表符缩进。

在markdown翻译为html时，一个段落中的换行符不会翻译为html的换行标签
, 也就是说，markdown一个段落的数行对应html的一行。
这样做的好处是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, 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 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");

列表

markdown支持有序列表和无序列表。

无序列表使用 *， +， -， 作为列表标识符。三者是等价的：

*   Red
*   Green
*   Blue

和

+   Red
+   Green
+   Blue

以及

-   Red
-   Green
-   Blue

的效果都是：

• Red
• Green
• Blue

有序列表的标识符是数字紧接英文句点。 值得注意的是用来标识有序列表的数字并不影响产生的html。例如：

1.  Bird
2.  McHale
3.  Parish

和

1.  Bird
1.  McHale
1.  Parish

以及

3. Bird
1. McHale
8. Parish

产生的html都是：

Bird
McHale
Parish

列表标识符位于行首，至多可以缩进3个空格。列表标识符和内容之间必须有一个以上的空格或一个制表符。

如果列表某一项有多个markdown段落，那么从第二个段落起，每个段落的首行必须缩进四个空格或一个制表符：

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.

如果要在列表中引用区块，区块引用标记 > 必须缩进四个空格或一个制表符：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要在列表中引用代码块，代码块需要缩进两次，也就是八个空格或两个制表符:

*   A list item with a code block:

    

代码块

代码块由缩进的一行或连续多行组成。当翻译成html时，代码块前后会分别加上

和

标签。例如，下列markdown：

This is a normal paragraph:

    This is a code block.

会产生如下html：

This is a normal paragraph:

This is a code block.

区段元素

链接

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

行内式：[链接文字](URL “可选的链接的title属性”)。 例如：

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

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

会产生如下html：

This is an example inline link.

This link has no title attribute.

参考式：[链接文字][链接标识符]。然后， 在文档的任意一行，定义链接：

[链接标识符]: URL "可选的连接的title属性"

注意事项：

• 行内只能有上面所示的链接定义的语法，否则，链接的定义会失效。例如：

  [google][1]
  [1]: google.com "google" foobar
  

  生成的html是

  [google][1]
  [1]: google.com "google" foobar
  

• ：和 URL 之间要有一个以上的空格或制表符。

• 链接标识符可以含有字母，数字，空格和标点符号，但不区分大小写。

• 可以省略链接标识符，而直接将链接文本作为标识符，这称为隐式链接。例如：

  [google][]
  [google]: google.com
  

  会生成

  google
  

强调

如果需要强调某些文字，可以使用 * 或 _ 包围它们。单个 * 或 _ 会翻译为, 两个 * 或 两个 _ 会翻译为 。惟一的限制是 * 和 _ 不能混用。例如：

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

会生成如下html:

single asterisks

single underscores

double asterisks

double underscores

行内代码

如果需要表示一段行内代码，使用反引号包围行内代码。例如:

Use the `printf()` function.

会生成如下html:

Use the printf() function.

图片

markdown标记图片的语法与链接很相似。

行内式：![替代文字](URL "可选的图片title属性")

参考式：![替代文字][标识符]
      [标识符]: URL "可选的图片title属性"

其它

自动链接

把URL和邮箱地址用尖括号括起来，markdown就会把它们翻译成html中的链接，其中的URL和邮箱地址作为链接文字。例如：

会被翻译为:

http://example.com/

html与markdown

任何无法用markdown语法表达的标记，你都可以直接用html，无须提前声明你将从使用markdown语法转为使用html语法。

html区块元素

html区块元素——如

, ,

, 
等元素——的使用有一些限制：
 
  
 
   
如同markdown段落一样，html区块元素前后都要有至少一个以上的空行。
 
   
开始标签与结束标签必须在行首，不能缩进。
 
   
markdown语法在html区块元素内无效。
 
  
 
  
一个例子：
 
  
This is a regular paragraph.

Foo

This is another regular paragraph.

html区段元素

与html区块元素不同，html区段元素可以在markdown的段落，标题，列表中随意使用，并且markdown语法在html区段元素中有效。

转义字符

反斜线转义

以下是markdown语法用到的标点符号：

\ 反斜线
` 反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

要生成上述标点符号，必须使用反斜线转义，例如要打出星号：

\*literal asterisks\*

自动转义

在html中，有两个字符需要特殊处理： < 和 & 。< 可以用来表示html标签的开始， &可以用来表示html实体。

markdown将会根据不同的情况，决定是否自动转义。

如果&是html实体的一部分，则保留原状，否则&会被翻译为&。

所以，如果你要插入一个版权符号，你可以这样写：

©

对应的html仍然是：

©

如果你写：

AT&T

markdown会翻译为：

AT&T

同样的，如果 < 表示html标签的开始，则保持原状，否则翻译为<。

在markdown代码区块和代码区段中，< 和 & 一定会被翻译为<和&。

这样，你就不再需要考虑麻烦的 < 和 & 的转义问题，因为markdown已经帮你处理好了。

参考文档

• DARING FIREBALL markdown syntax
• markdown语法说明