markdown語法

概述

哲學

Markdown 的目標是易讀易寫。

Markdown強調可讀性高於一切。一份Markdown格式的文檔應該能直接以純文本方式發佈，而不致一眼看過去滿眼都是標籤和格式化指令。Markdown的語法確實受了幾種現有的text轉HTML過濾器影響－－包括 Setext, atx, Textile, reStructuredText,Grutatext, 和 EtText -- 其中對Markdown語法影響最大的單一來源是純文本的Email格式。

爲實現這一目標，Markdown的語法幾乎所有由標點符號構成，這些標點符號都是精心挑選而來，儘可能作到能望文生義。如星號括着一個單詞（Markdown中表示強調）看上去就像 *強調*。Markdown的列表看上去就像列表；Markdown的引文就象引文，和你使用email時的感受同樣。

內嵌HTML

Markdown的語法爲「方便地在網上寫做」這一目標而生。

Markdown不是HTML替代品，也不是爲了終接HTML。它的語法很是簡單，只至關於HTML標籤的一個很是很是小的子集。它並不是是爲了更容易輸入HTML標籤而創造一種新語法。在我看來，HTML標籤已經夠容易書寫的了。Markdown的目標是讓（在網上）讓讀文章、寫文章、修改文章更容易。HTML是一種適合發表的格式；而Markdown是一種書寫格式。正因如此，Markdown的格式化語法僅需解決用純文本表達的問題。

對Markdown語法沒法支持的格式，你能夠直接用HTML。你不須要事先聲明或者使用什麼定界符來告訴Markdown要寫HTML了，你直接寫就是了。

惟一的限制是那些塊級HTML元素 -- 如 <div>,<table>, <pre>, <p>等等 -- 必須使用空行與相鄰內容分開，而且塊元素的開始和結束標籤以前不要留有空格或TAB。Markdown足夠聰明不會添加額外的(也是沒必要要的)<p>標籤包住這些塊元素標籤。

下面這個例子，在一篇Markdown文章中添加了一個HTML表格：

這是一個普通的段落。 <table> <tr> <td>Foo</td> </tr> </table> 這是另外一個普通的段落。

注意一點，不要在塊級HTML元素內使用Markdown格式化命令，Markdown不會處理它們。好比你不要在一個HTML塊中使用 *emphasis* 這樣的Markdown格式化命令。

行內HTML標籤 -- 如 <span>, <cite>, 或 <del> -- 在一個Markdown段落裏、列表中、或者標題中－－隨便用。 若是須要，你甚至能夠用HTML標籤代替Markdown格式化命令。比方你能夠直接用HTML標籤 <a> 或 <img> 而不使用Markdown的連接和圖片語法，隨你的便。

不一樣於這些塊級HTML元素，在HTML行內元素內的Markdown語法標記會被正確處理。

自動轉換特殊字符

在HTML中，有兩個字符須要特殊對待：<和 &。<用於標籤開始，&用於標識HTML實體。若是打算把它們當成普通字符，你必須使用反引號轉義它們，如<和&。

對一些互聯網做家來講，&符號特別令人煩惱。若是你打算寫'AT&T'，你就得寫 'AT&T'。甚至在URL中也得想着轉義&符號。比方你打算寫：

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

你就得在A標籤中把href屬性中的URL編碼成：

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

不用說，這很容易忘。這每每是那些良構HTML站點中最容易出錯的地方。

在Markdown中，你儘管天然的使用這些字符，只須要關心那些必要的轉義。若是使用在HTML實體中使用&符號，它會保持不變；而在其它場合，它會轉換成&。

因此，若是你打算在文章中書寫版權符號，你能夠這樣寫：

©

Markdown不會碰它。然而若是你書寫

AT&T

Markdown就會把它翻譯成：

AT&T

相似的，既然Markdown支持內嵌HTML，若是你使用<做爲HTML標籤訂界符，Markdown就會把它們當成HTML標籤訂界符。但是若是你書寫：

4 < 5

Markdown就會把它翻譯成：

4 < 5

然而，在Mardown代碼行內標記和塊級標記之中，<和&始終會被自動編碼。這使得在Markdown文件中書寫HTML代碼更容易.(相對於純HTML。若是想在純在純HTML裏貼一段HTML代碼，那纔是糟糕透頂，必須對代碼中的每個<和&都轉義才成。)

塊級元素

段落和換行

一個段落由一行或多個相關文本行構成。段落之間用一個或多個空行分隔。（一個空行就是一個看上去什麼也沒有的行－－若是一行什麼也沒有或者只有空格和TAB都會被視爲空行）正常的段落不要以空白或TAB字符開始。

一行或多個相關文本行意味着Markdown支持「硬折行」。這一點與其它text轉HTML的程序徹底不一樣（包括Moveable Type的「Convert Line Breaks」選項），它們會將段落中的每個換行符轉換成<br />標籤。

若是你確實須要使用Markdown插入一個<br />換行符，只須要在每一行的末尾以兩個或更多個空格符號結束，而後再打回車鍵。

沒錯，在Markdown裏生成一個<br />稍稍有一點麻煩，但那種簡單的「把每個換行符都轉換成<br />規則」並不適用於Markdown。Markdown Email風格的 blockquoting 和 multi-paragraph list items更好用 -- 而且更美觀 -- 在你用換行符對其格式化時。

標題

Markdown 支持兩種風格的標題，Setext 和 atx.

Setext-風格的一級標題下面一行使用等號符號，二級標題下面使用連字符符號，例如：

這是一個一級標題 ============= 這是一個二級標題 -------------

至少有一個=和-就能正常工做。

Atx-風格的標題在每行的開頭使用1－6個井號字符，分別對應標題級別1－6。例如：

# 這是一級標題 ## 這是二級標題 ###### 這是六級標題

若是願意, 你也能夠 "結束" atx-風格的標題。這純粹是美觀考慮--若是你以爲這樣會看上更舒服些的話。結束用的井號個數隨便，沒必要與起始井號數量相同 (起始井號的數量決定標題級別)：

# 這是一級標題 # ## 這是二級標題 ## ### 這是三級標題 ######

引用塊

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, 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裏，你就能夠選中一些文字以後從Text菜單裏選擇引用級別。

列表

Markdown 支持有序列表和無序列表

無序列表可以使用星號、加號和連字符（這幾個符號是等價的，你喜歡哪一個就用哪一個）做爲列表標記：

* Red * Green * Blue

等同於：

+ Red + Green + Blue

也等同於：

- Red - Green - Blue

有序列表則使用數字加英文句點：

1. Bird 2. McHale 3. Parish

有一點須要注意，你在列表中輸入的標記數字並不會反映到Markdown輸出的HTML之中。上面這個列表Markdown會輸出爲：

<ol> <li>Bird</li> <li>McHale</li> <li>Parish</li> </ol>

即便你寫成下面這樣：

1. Bird 1. McHale 1. Parish

甚至這樣：

3. Bird 1. McHale 8. Parish

都會獲得如出一轍（但正確的）輸出。要點在於，若是你願意，就在你的Markdown有序列表裏順序使用數字（這樣源代碼裏的順序和生成的順序會一致），若是你但願省點兒事，你就不用費心（去手工編號）。

若是你打算偷懶，記住列表的第一行使用數字 1。之後Markdown或許會支持有序列表從任意數字開始（譯者注：這兒和前面的例子有點矛盾，原文如此）。

列表標記一般從左邊界開始，至多能夠有三個空格的縮進。列表標記以後至少要跟一個空格或TAB。

爲了讓列表看起來美觀，你可使用TAB縮進列表項內容，使其整齊:

* 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就會在HTML輸出中使用<p>標籤包裹列表項。好比：

* Bird * Magic

生成的HTML以下：

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

而這個：

* Bird * Magic

生成的HTML是這樣：

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

列表項有可能由多個段落組成，列表項的每一個後續段落必須縮進至少4個空格或者一個TAB：

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.

像上面這樣縮進後續段落的每一行看起來很美觀（但稍有些麻煩），若是你比較懶（和我同樣），沒問題，Markdown支持你：

* 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個空格或者兩個TAB：

* A list item with a code block: <code goes here>

有時候不當心會觸發一個有序列表，比方在寫相似下面這樣的東西時：

1986. What a great season.

換言之， 以數字＋句點＋空格 序列起始的行會觸發有序列表。爲避免此狀況，要對句點符號進行轉義：

1986\. What a great season.

代碼塊

咱們常常在寫有關編程或標記語言源代碼時用到預格式化的代碼塊。不像格式化普通段落，代碼塊中的行會按字面進行解釋。Markdown對代碼塊同時使用<pre> 和 <code>標籤包裹：

在Markdown中要生成一個代碼塊，只須要在代碼塊內容的每一行縮進至少四個空格或者一個TAB。好比：

This is a normal paragraph: This is a code block.

Markdown會生成：

<p>This is a normal paragraph:</p> <pre><code>This is a code block.</code></pre>

Markdown會從生成的代碼塊中刪除一級縮進 -- 4個空格或者1個TAB。看下面這個例子：

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>

代碼塊在遇到沒有縮進的一行，或者文件末尾時自動結束。

在代碼塊中，&符號和<、>會自動轉換成HTML實體。所以在Markdown中包含HTML源代碼只是小菜一碟－－粘貼進去，縮進一下。剩下的髒活累活Markdown自會處理。看下面這個例子：

 <div class="sample_footer"> &copy; 2004 Foo Corporation </div>

Markdown會生成：

 
 
 
    
 
  © 
 
    
 
  2004 
 
    
 
  Foo 
 
    
 
  Corporation 
 
    

 
 

Markdown不會解析代碼塊中的Markdown標記。如代碼塊中的星號就是星號，失去了它原來的Markdown含義。這意味着你可以使用Markdown編寫Markdown本身的語法教程。（就象這篇文章同樣）。

水平線

若是在一行裏只放三個或更多個連字符，或星號或下劃線，你就會獲得一個水平線標記(<hr />)。下面每一行都會獲得一個水平線：

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

行內元素

連接

Markdown 支持兩種風格的連接： 行內連接 和 引用連接.

兩種風格的連接，連接文本都放在中括號以內[square brackets]。

要生成一個行內連接，在連接文本以後緊跟用一對小括號。小括號裏放連接地址和可選的的連接title。若是提供連接title的話，連接title要用引號包起來。例如：

這是一個 [an example](http://example.com/ "Title") 行內連接。 [這個連接](http://example.net/) 沒有title屬性。

Markdown會生成：

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

若是你打算引用一個本地資源或者同一站點的資源，可使用相對路徑：

若是想進一步瞭解我，請參閱個人 [關於我](/about/) 頁。

引用風格的連接，在連接文本以後緊跟又一對中括號。這對中括號裏放的是該連接的標識符（能夠理解爲別名）：

這是一個引用型連接 [示例][id]。

若是你嫌棄兩對中括號過於親密，Markdown容許你在兩對中括號之間放一個空格：

這是一個引用型連接 [示例] [id]。

而後，咱們能夠在文檔的任意位置，像下面這樣定義連接標識與連接的對應關係（一行一個連接）：

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

即：

• 中括號內放連接標識符(行前可選縮進，至多不超過三個空格)；
• 以後緊跟一個冒號；
• 再後面是一個或多個空格（TAB也行）；
• 接下來是連接URL；
• 最後面是可選的用雙引號或單引號或小括號括起來的連接title。

下面三種連接定義方式是等價的：

[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 版本有一個已知的bug，用單引號做爲連接title的定界符會出問題。

至於連接URL，還支持使用一對可選的尖括號包裹起來：

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

你也能夠將連接的title屬性放在下一行並使用額外的空格或TAB填充，這樣較長的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 10 times more traffic from [Google] [11] than from [Yahoo] [12] or [MSN] [13]. [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"

上面兩種寫法最終獲得HTML輸出是同樣的：

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

做爲比較，下面這個段落使用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則有234個字符。純HTML中標記字符甚至超過了文本自己。

使用Markdown的引用型連接，源文檔更接近於最終的瀏覽器輸出效果。再加上Markdown容許將標記有關的元數據移到段落以外，你儘管添加連接，而沒必要擔憂打斷文件的故事情節。

強調

Markdown使用星號(*)和下劃線(_)做爲表示強調。用一個 * 或 _ 包裹的文本會使用 HTML<em> 標籤包裹; 用兩個 * 或 _包裹的文本會使用HTML<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

不過若是你用空格包裹單獨的 * 或 _，它們就失去了強調的含義，而成爲字面上的星號或下劃線。

若是不想讓Markdown解釋這兩個元字符，就轉義它：

\*this text is surrounded by literal asterisks\*

代碼

要在行內表示部分代碼，用反引號(`)包住它。與預格式代碼塊不一樣和，行內代碼用於段落以內。例如：

Use the `printf()` function.

會生成：

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

要在一個行內代碼中使用反引號（`）自己，用多個反引號做爲定界符包住它：

``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>

在行內代碼中，&和<和>會自動編碼爲HTML實體，以方便包含HTML標籤。Markdown會把下面這行：

Please don't use any `<blink>` tags.

轉換爲：

<p>Please don't use any <code><blink></code> tags.</p>

你也能夠這樣寫：

`—` is the decimal-encoded equivalent of `—`.

會獲得：

<p><code>&#8212;</code> is the decimal-encoded equivalent of <code>&mdash;</code>.</p>

圖片

必須認可，要以「天然的」語法把一個圖片放到一個純文本文檔之中，確實是一個挑戰。

Markdown使用了相似連接語法來表示圖片，一樣有兩種風格：行內圖片和引用圖片。

行內圖片語法示例：

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

即：

• 一個感嘆號!開頭；
• 其後緊跟一對中括號，中括號內存放圖片的alt`屬性；
• 其後緊跟一對小括號，小括號內存放圖片的URL或路徑，及可選的用雙引號或單引號或小括號括起來的圖片title

引用圖片語法以下：

![Alt text][id]

這裏 "id" 是圖片引用標識。圖片引用定義的語法與連接定義徹底相同：

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

在寫這篇文章時，Markdown尚未語法指定圖片的大小，若是這一點對你特別重要，你能夠直接使用<img>標籤。

雜七雜八

自動連接

Markdown提供了一種快捷方式"自動地"定義連接和Email地址：直接用一對尖括號把URL或Email地址包住。這表示連接文本就是URL自己，Email文本就是Email自己。這樣你就獲得了一個可點擊的連接，如：

<http://example.com/>

Markdown會將它轉換爲：

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

自動Email地址工做方式類似，只有一點不一樣。Markdown自動的用一些十進制和十六進制數字表示你的Email，以防止遭遇垃圾郵件襲擊。 例如：

<address@example.com>

會被轉換爲：

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65; &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111; &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61; &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

瀏覽器會將它渲染爲一個可點擊的連接，並正確顯示 "address@example.com"。

(這種實體編碼的小方法能夠騙過一些收集郵件地址的機器人，不過它確實沒法騙過全部的機器人。有總比沒有強，聊勝於無。能阻止一點就阻止一點好了。)

反斜線轉義

Markdown容許你使用反斜線轉義那些Markdown元字符，讓它們失去原有的「魔力」。舉個例子，若是你確實想用星號包住一個詞組（而不是想獲得<em>標籤），就能夠在星號以前使用反斜線將其轉義。即：

\*literal asterisks\*

Markdown中，如下字符支持使用反斜線轉義：

\ 反斜線 ` 反引號 * 星號 _ 下劃線 {} 大括號 [] 中括號 () 小括號 # 井號 + 加號 - 減號（連字符） . 句點 ! 感嘆號