Markdown文件

NOTE: This is Traditional Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to Markdown: Syntax.

Markdown: Syntax

• 概述
  • 哲學(xué)
  • 行內(nèi) HTML
  • 特殊字元自動轉(zhuǎn)換
• 區(qū)塊元素
  • 段落和換行
  • 標(biāo)題
  • 區(qū)塊引言
  • 清單
  • 程式碼區(qū)塊
  • 分隔線
• 區(qū)段元素
  • 連結(jié)
  • 強(qiáng)調(diào)
  • 程式碼
  • 圖片
• 其他
  • 跳脫字元
  • 自動連結(jié)
• 感謝

**注意：**這份文件是用Markdown寫的，你可以看看它的原始檔 。

概述

哲學(xué)

Markdown的目標(biāo)是實(shí)現(xiàn)「易讀易寫」。

不過最需要強(qiáng)調(diào)的便是它的可讀性。一份使用Markdown格式撰寫的文件應(yīng)該可以直接以純文字發(fā)佈，並且看起來不會像是由許多標(biāo)籤或是格式指令所構(gòu)成。Markdown語法受到一些既有text-to-HTML格式的影響，包括Setext、atx、Textile、reStructuredText、Grutatext 和 EtText，然而最大靈感來源其實(shí)是純文字的電子郵件格式。

因此Markdown的語法全由標(biāo)點(diǎn)符號所組成，並經(jīng)過嚴(yán)謹(jǐn)慎選，是為了讓它們看起來就像所要表達(dá)的意思。像是在文字兩旁加上星號，看起來就像*強(qiáng)調(diào)*。Markdown的清單看起來，嗯，就是清單。假如你有使用過電子郵件，區(qū)塊引言看起來就真的像是引用一段文字。

行內(nèi)HTML

Markdown的語法有個主要的目的：用來作為一種網(wǎng)路內(nèi)容的寫作用語言。

Markdown不是要來取代HTML，甚至也沒有要和它相似，它的語法種類不多，只和HTML的一部分有關(guān)係，重點(diǎn)不是要創(chuàng)造一種更容易寫作HTML文件的語法，我認(rèn)為HTML已經(jīng)很容易寫了，Markdow的重點(diǎn)在於，它能讓文件更容易閱讀、編寫。HTML 是一種發(fā)佈的格式，Markdown是一種編寫的格式，因此，Markdown的格式語法只涵蓋純文字可以涵蓋的範(fàn)圍。

不在Markdown涵蓋範(fàn)圍之外的標(biāo)籤，都可以直接在文件裡面用HTML撰寫。不需要額外標(biāo)註這是HTML或是Markdown；只要直接加標(biāo)籤就可以了。

只有區(qū)塊元素──比如<div>、<table>、<pre>、<p>等標(biāo)籤，必需在前後加上空行，以利與內(nèi)容區(qū)隔。而且這些（元素）的開始與結(jié)尾標(biāo)籤，不可以用tab或是空白來縮排。Markdown的產(chǎn)生器有智慧型判斷，可以避免在區(qū)塊標(biāo)籤前後加上沒有必要的<p>標(biāo)籤。

舉例來說，在Markdown文件裡加上一段HTML表格：

This is a regular paragraph.

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

This is another regular paragraph.

請注意，Markdown語法在HTML區(qū)塊標(biāo)籤中將不會被進(jìn)行處理。例如，你無法在HTML區(qū)塊內(nèi)使用Markdown形式的*強(qiáng)調(diào)*。

HTML的區(qū)段標(biāo)籤如<span>、<cite>、<del>則不受限制，可以在Markdown的段落、清單或是標(biāo)題裡任意使用。依照個人習(xí)慣，甚至可以不用Markdown格式，而採用HTML標(biāo)籤來格式化。舉例說明：如果比較喜歡HTML的 <a>或<img>標(biāo)籤，可以直接使用這些標(biāo)籤，而不用Markdown提供的連結(jié)或是影像標(biāo)示語法。

HTML區(qū)段標(biāo)籤和區(qū)塊標(biāo)籤不同，在區(qū)段標(biāo)籤的範(fàn)圍內(nèi)，Markdown的語法是有效的。

特殊字元自動轉(zhuǎn)換

在HTML文件中，有兩個字元需要特殊處理：<和&。<符號用於起始標(biāo)籤&符號則用於標(biāo)記HTML實(shí)體，如果你只是想要使用這些符號，你必須要使用實(shí)體的形式，像是<和&。

& 符號其實(shí)很容易讓寫作網(wǎng)路文件的人感到困擾，如果你要打「AT&T」 ，你必須要寫成「AT&T」 ，還得轉(zhuǎn)換網(wǎng)址內(nèi)的 & 符號，如果你要連結(jié)到：

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

你必須要把網(wǎng)址轉(zhuǎn)成：

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

才能放到連結(jié)標(biāo)籤的href屬性裡。不用說也知道這很容易忘記，這也可能是HTML標(biāo)準(zhǔn)檢查所檢查到的錯誤中，數(shù)量最多的。

Markdown允許你直接使用這些符號，但是你要小心跳脫字元的使用，如果你是在HTML實(shí)體中使用&符號的話，它不會被轉(zhuǎn)換，而在其他情形下，它則會被轉(zhuǎn)換成&。所以你如果要在文件中插入一個著作權(quán)的符號，你可以這樣寫：

©

Markdown將不會對這段文字做修改，但是如果你這樣寫：

AT&T

Markdown就會將它轉(zhuǎn)為：

AT&T

類似的狀況也會發(fā)生在<符號上，因?yàn)镸arkdown支援行內(nèi) HTML ，如果你是使用<符號作為HTML標(biāo)籤使用，那Markdown也不會對它做任何轉(zhuǎn)換，但是如果你是寫：

4 < 5

Markdown將會把它轉(zhuǎn)換為：

4 < 5

不過需要注意的是，code範(fàn)圍內(nèi)，不論是行內(nèi)還是區(qū)塊，<和&兩個符號都一定會被轉(zhuǎn)換成HTML實(shí)體，這項(xiàng)特性讓你可以很容易地用Markdown寫HTML code（和HTML相對而言。在HTML語法中，你要把所有的<和&都轉(zhuǎn)換為 HTML實(shí)體，才能在HTML文件裡面寫出HTML code。）

區(qū)塊元素

段落和換行

一個段落是由一個以上相連接的行句組成，而一個以上的空行則會切分出不同的段落（空行的定義是顯示上看起來像是空行，便會被視為空行。比方說，若某一行只包含空白和tab，則該行也會被視為空行），一般的段落不需要用空白或斷行縮排。

「一個以上相連接的行句組成」這句話其實(shí)暗示了Markdown允許段落內(nèi)的強(qiáng)迫斷行，這個特性和其他大部分的text-to-HTML格式不一樣（包括 MovableType的「Convert Line Breaks」選項(xiàng)），其他的格式會把每個斷行都轉(zhuǎn)成<br />標(biāo)籤。

如果你真的想要插入<br />標(biāo)籤的話，在行尾加上兩個以上的空白，然後按enter。

是的，這確實(shí)需要花比較多功夫來插入<br />，但是「每個換行都轉(zhuǎn)換為<br />」的方法在Markdown中並不適合， Markdown中email式的區(qū)塊引言和多段落的清單在使用換行來排版的時候，不但更好用，還更好閱讀。

標(biāo)題

Markdown支援兩種標(biāo)題的語法，Setext和atx形式。

Setext形式是用底線的形式，利用=（最高階標(biāo)題）和-（第二階標(biāo)題），例如：

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

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

任何數(shù)量的=和-都可以有效果。

Atx形式則是在行首插入1到6個 # ，各對應(yīng)到標(biāo)題1到6階，例如：

# This is an H1

## This is an H2

###### This is an H6

你可以選擇性地「關(guān)閉」atx樣式的標(biāo)題，這純粹只是美觀用的，若是覺得這樣看起來比較舒適，你就可以在行尾加上#，而行尾的#數(shù)量也不用和開頭一樣（行首的井字?jǐn)?shù)量決定標(biāo)題的階數(shù)）：

# This is an H1 #

## This is an H2 ##

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

區(qū)塊引言

Markdown使用email形式的區(qū)塊引言，如果你很熟悉如何在email信件中引言，你就知道怎麼在Markdown文件中建立一個區(qū)塊引言，那會看起來像是你強(qiáng)迫斷行，然後在每行的最前面加上>：

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

區(qū)塊引言可以有階層（例如：引言內(nèi)的引言），只要根據(jù)層數(shù)加上不同數(shù)量的>：

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

引言的區(qū)塊內(nèi)也可以使用其他的Markdown語法，包括標(biāo)題、清單、程式碼區(qū)塊等：

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

任何標(biāo)準(zhǔn)的文字編輯器都能簡單地建立email樣式的引言，例如BBEdit，你可以選取文字後然後從選單中選擇增加引言階層。

清單

Markdown支援有序清單和無序清單。

無序清單使用星號、加號或是減號作為清單標(biāo)記：

*   Red
*   Green
*   Blue

等同於：

+   Red
+   Green
+   Blue

也等同於：

-   Red
-   Green
-   Blue

有序清單則使用數(shù)字接著一個英文句點(diǎn)：

1.  Bird
2.  McHale
3.  Parish

很重要的一點(diǎn)是，你在清單標(biāo)記上使用的數(shù)字並不會影響輸出的HTML結(jié)果，上面的清單所產(chǎn)生的HTML標(biāo)記為：

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

如果你的清單標(biāo)記寫成：

1.  Bird
1.  McHale
1.  Parish

或甚至是：

3. Bird
1. McHale
8. Parish

你都會得到完全相同的HTML輸出。重點(diǎn)在於，你可以讓Markdown文件的清單數(shù)字和輸出的結(jié)果相同，或是你懶一點(diǎn)，你可以完全不用在意數(shù)字的正確性。

如果你使用懶惰的寫法，建議第一個項(xiàng)目最好還是從「1.」開始，因?yàn)镸arkdown未來可能會支援有序清單的start屬性。

清單項(xiàng)目標(biāo)記通常是放在最左邊，但是其實(shí)也可以縮排，最多三個空白，項(xiàng)目標(biāo)記後面則一定要接著至少一個空白或tab。

要讓清單看起來更漂亮，你可以把內(nèi)容用固定的縮排整理好：

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

如果清單項(xiàng)目間用空行分開， Markdown會把項(xiàng)目的內(nèi)容在輸出時用<p>標(biāo)籤包起來，舉例來說：

*   Bird
*   Magic

會被轉(zhuǎn)換為：

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

但是這個：

*   Bird

*   Magic

會被轉(zhuǎn)換為：

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

清單項(xiàng)目可以包含多個段落，每個項(xiàng)目下的段落都必須縮排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.

如果你每行都有縮排，看起來會看好很多，當(dāng)然，再次地，如果你很懶惰，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.

如果要在清單項(xiàng)目內(nèi)放進(jìn)引言，那>就需要縮排：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要放程式碼區(qū)塊的話，該區(qū)塊就需要縮排兩次，也就是8個空白或是兩個tab：

*   A list item with a code block:

        <code goes here>

當(dāng)然，項(xiàng)目清單很可能會不小心產(chǎn)生，像是下面這樣的寫法：

1986. What a great season.

換句話說，也就是在行首出現(xiàn)數(shù)字－句點(diǎn)－空白，要避免這樣的狀況，你可以在句點(diǎn)前面加上反斜線。

1986\. What a great season.

程式碼區(qū)塊

和程式相關(guān)的寫作或是標(biāo)籤語言原始碼通常會有已經(jīng)排版好的程式碼區(qū)塊，通常這些區(qū)塊我們並不希望它以一般段落文件的方式去排版，而是照原來的樣子顯示，Markdown會用<pre>和<code>標(biāo)籤來把程式碼區(qū)塊包起來。

要在Markdown中建立程式碼區(qū)塊很簡單，只要簡單地縮排4個空白或是1個tab就可以，例如，下面的輸入：

This is a normal paragraph:

    This is a code block.

Markdown會轉(zhuǎn)換成：

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

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

這個每行一階的縮排（4個空白或是1個tab），都會被移除，例如：

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

會被轉(zhuǎn)換為：

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

一個程式碼區(qū)塊會一直持續(xù)到?jīng)]有縮排的那一行（或是文件結(jié)尾）。

在程式碼區(qū)塊裡面，&、<和>會自動轉(zhuǎn)成HTML實(shí)體，這樣的方式讓你非常容易使用Markdown插入範(fàn)例用的HTML原始碼，只需要複製貼上，再加上縮排就可以了，剩下的Markdown都會幫你處理，例如：

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