# Markdown 文件
==================
**NOTE:** This is Traditional Chinese Edition Document of
Markdown Syntax. If you are seeking for English Edition
Document. Please refer to [Markdown: Syntax][eng-doc].
[eng-doc]:http://daringfireball.net/projects/markdown/syntax
Markdown: Syntax
================
* ? [概述](#overview)
? ?* ? [哲學](#philosophy)
? ?* ? [行內 HTML](#html)
? ?* ? [特殊字元自動轉換](#autoescape)
* ? [區塊元素](#block)
? ?* ? [段落和換行](#p)
? ?* ? [標題](#header)
? ?* ? [區塊引言](#blockquote)
? ?* ? [清單](#list)
? ?* ? [程式碼區塊](#precode)
? ?* ? [分隔線](#hr)
* ? [區段元素](#span)
? ?* ? [連結](#link)
? ?* ? [強調](#em)
? ?* ? [程式碼](#code)
? ?* ? [圖片](#img)
* ? [其它](#misc)
? ?* ? [跳脫字元](#backslash)
? ?* ? [自動連結](#autolink)
* ? [感謝](#acknowledgement)
**注意：**這份文件是用 Markdown 寫的，你可以[看看它的原始檔][src] 。
?[src]: https://github.com/othree/markdown-syntax-zhtw/blob/master/syntax.md
* * *
<h2 id="overview">概述</h2>
<h3 id="philosophy">哲學</h3>
Markdown 的目標是實現「易讀易寫」。
不過最需要強調的便是它的可讀性。一份使用 Markdown 格式撰寫的文件應該可以直接以純文字發佈，並且看起來不會像是由許多標籤或是格式指令所構成。Markdown 語法受到一些既有 text-to-HTML 格式的影響，包括 [Setext] [1]、[atx] [2]、[Textile] [3]、[reStructuredText] [4]、[Grutatext] [5] 和 [EtText] [6]，然而最大靈感來源其實是純文字的電子郵件格式。
?[1]: http://docutils.sourceforge.net/mirror/setext.html
?[2]: http://www.aaronsw.com/2002/atx/
?[3]: http://textism.com/tools/textile/
?[4]: http://docutils.sourceforge.net/rst.html
?[5]: http://www.triptico.com/software/grutatxt.html
?[6]: http://ettext.taint.org/doc/
因此 Markdown 的語法全由標點符號所組成，並經過嚴謹慎選，是為了讓它們看起來就像所要表達的意思。像是在文字兩旁加上星號，看起來就像\*強調\*。Markdown 的清單看起來，嗯，就是清單。假如你有使用過電子郵件，區塊引言看起來就真的像是引用一段文字。
<h3 id="html">行內 HTML</h3>
Markdown 的語法有個主要的目的：用來作為一種網路內容的*寫作*用語言。
Markdown 不是要來取代 HTML，甚至也沒有要和它相似，它的語法種類不多，只和 HTML 的一部分有關係，重點*不是*要創造一種更容易寫作 HTML 文件的語法，我認為 HTML 已經很容易寫了，Markdown 的重點在於，它能讓文件更容易閱讀、編寫。HTML 是一種*發佈*的格式，Markdown 是一種*編寫*的格式，因此，Markdown 的格式語法只涵蓋純文字可以涵蓋的範圍。
不在 Markdown 涵蓋範圍之外的標籤，都可以直接在文件裡面用 HTML 撰寫。不需要額外標註這是 HTML 或是 Markdown；只要直接加標籤就可以了。
只有區塊元素──比如 `<div>`、`<table>`、`<pre>`、`<p>` 等標籤，必須在前後加上空行，以利與內容區隔。而且這些（元素）的開始與結尾標籤，不可以用 tab 或是空白來縮排。Markdown 的產生器有智慧型判斷，可以避免在區塊標籤前後加上沒有必要的 `<p>` 標籤。
舉例來說，在 Markdown 文件裡加上一段 HTML 表格：
? ?This is a regular paragraph.
? ?<table>
? ? ? ?<tr>
? ? ? ? ? ?<td>Foo</td>
? ? ? ?</tr>
? ?</table>
? ?This is another regular paragraph.
請注意，Markdown 語法在 HTML 區塊標籤中將不會被進行處理。例如，你無法在 HTML 區塊內使用 Markdown 形式的`*強調*`。
HTML 的區段標籤如 `<span>`、`<cite>`、`<del>` 則不受限制，可以在 Markdown 的段落、清單或是標題裡任意使用。依照個人習慣，甚至可以不用Markdown 格式，而採用 HTML 標籤來格式化。舉例說明：如果比較喜歡 HTML 的 ?`<a>` 或 `<img>` 標籤，可以直接使用這些標籤，而不用 Markdown 提供的連結或是影像標示語法。
HTML 區段標籤和區塊標籤不同，在區段標籤的範圍內， Markdown 的語法是有效的。
<h3 id="autoescape">特殊字元自動轉換</h3>
在 HTML 文件中，有兩個字元需要特殊處理： `<` 和 `&` 。 `<` 符號用於起始標籤，`&` 符號則用於標記 HTML 實體，如果你只是想要使用這些符號，你必須要使用實體的形式，像是 `<` 和 `&`。
`&` 符號其實很容易讓寫作網路文件的人感到困擾，如果你要打「AT&T」 ，你必須要寫成「`AT&T`」 ，還得轉換網址內的 `&` 符號，如果你要連結到：
? ?http://images.google.com/images?num=30&q=larry+bird
你必須要把網址轉成：
? ?http://images.google.com/images?num=30&q=larry+bird
才能放到連結標籤的 `href` 屬性裡。不用說也知道這很容易忘記，這也可能是 HTML 標準檢查所檢查到的錯誤中，數量最多的。
Markdown 允許你直接使用這些符號，但是你要小心跳脫字元的使用，如果你是在HTML 實體中使用 `&` 符號的話，它不會被轉換，而在其它情形下，它則會被轉換成 `&`。所以你如果要在文件中插入一個著作權的符號，你可以這樣寫：
? ??
Markdown 將不會對這段文字做修改，但是如果你這樣寫：
? ?AT&T
Markdown 就會將它轉為：
? ?AT&T
類似的狀況也會發生在 `<` 符號上，因為 Markdown 支援 [行內 HTML](#html) ，如果你是使用 `<` 符號作為 HTML 標籤使用，那 Markdown 也不會對它做任何轉換，但是如果你是寫：
? ?4 < 5
Markdown 將會把它轉換為：
? ?4 < 5
不過需要注意的是，code 範圍內，不論是行內還是區塊， `<` 和 `&` 兩個符號都*一定*會被轉換成 HTML 實體，這項特性讓你可以很容易地用 Markdown 寫 HTML code （和 HTML 相對而言， HTML 語法中，你要把所有的 `<` 和 `&` 都轉換為 HTML 實體，才能在 HTML 文件裡面寫出 HTML code。）
* * *
<h2 id="block">區塊元素</h2>
<h3 id="p">段落和換行</h3>
一個段落是由一個以上相連接的行句組成，而一個以上的空行則會切分出不同的段落（空行的定義是顯示上看起來像是空行，便會被視為空行。比方說，若某一行只包含空白和 tab，則該行也會被視為空行），一般的段落不需要用空白或斷行縮排。
「一個以上相連接的行句組成」這句話其實暗示了 Markdown 允許段落內的強迫斷行，這個特性和其他大部分的 text-to-HTML 格式不一樣（包括 MovableType 的「Convert Line Breaks」選項），其它的格式會把每個斷行都轉成 `<br />` 標籤。
如果你*真的*想要插入 `<br />` 標籤的話，在行尾加上兩個以上的空白，然後按 enter。
是的，這確實需要花比較多功夫來插入 `<br />` ，但是「每個換行都轉換為 `<br />`」的方法在 Markdown 中並不適合， Markdown 中 email 式的 [區塊引言][bq] 和多段落的 [清單][l] 在使用換行來排版的時候，不但更好用，還更好閱讀。
?[bq]: #blockquote
?[l]: ?#list
<h3 id="header">標題</h3>
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
你可以選擇性地「關閉」atx 樣式的標題，這純粹只是美觀用的，若是覺得這樣看起來比較舒適，你就可以在行尾加上 `#`，而行尾的 `#` 數量也不用和開頭一樣（行首的井字數量決定標題的階數）：
? ?# This is an H1 #
? ?## This is an H2 ##
? ?### This is an H3 ######
<h3 id="blockquote">Blockquotes</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.
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 ，你可以選取文字後然後從選單中選擇*增加引言階層*。
<h3 id="list">清單</h3>
Markdown 支援有序清單和無序清單。
無序清單使用星號、加號或是減號作為清單標記：
? ?* ? Red
? ?* ? Green
? ?* ? Blue
等同於：
? ?+ ? Red
? ?+ ? Green
? ?+ ? Blue
也等同於：
? ?- ? Red
? ?- ? Green
? ?- ? Blue
有序清單則使用數字接著一個英文句點：
? ?1. ?Bird
? ?2. ?McHale
? ?3. ?Parish
很重要的一點是，你在清單標記上使用的數字並不會影響輸出的 HTML 結果，上面的清單所產生的 HTML 標記為：
? ?<ol>
? ?<li>Bird</li>
? ?<li>McHale</li>
? ?<li>Parish</li>
? ?</ol>
如果你的清單標記寫成：
? ?1. ?Bird
? ?1. ?McHale
? ?1. ?Parish
或甚至是：
? ?3. Bird
? ?1. McHale
? ?8. Parish
你都會得到完全相同的 HTML 輸出。重點在於，你可以讓 Markdown 文件的清單數字和輸出的結果相同，或是你懶一點，你可以完全不用在意數字的正確性。
如果你使用懶惰的寫法，建議第一個項目最好還是從 1. 開始，因為 Markdown 未來可能會支援有序清單的 start 屬性。
清單項目標記通常是放在最左邊，但是其實也可以縮排，最多三個空白，項目標記後面則一定要接著至少一個空白或 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 會把項目的內容在輸出時用 `<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 個空白或是一個 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.
<h3 id="precode">程式碼區塊</h3>
和程式相關的寫作或是標籤語言原始碼通常會有已經排版好的程式碼區塊，通常這些區塊我們並不希望它以一般段落文件的方式去排版，而是照原來的樣子顯示，Markdown 會用 `<pre>` 和 `<code>` 標籤來把程式碼區塊包起來。
要在 Markdown 中建立程式碼區塊很簡單，只要簡單地縮排 4 個空白或是 1 個 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>
這個每行一階的縮排（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="footer">
? ? ? ? ? ?? 2004 Foo Corporation
? ? ? ?</div>
會被轉換為：
? ?<pre><code><div class="footer">
? ? ? ?© 2004 Foo Corporation
? ?</div>
? ?</code></pre>
程式碼區塊中，一般的 Markdown 語法不會被轉換，像是星號便只是星號，這表示你可以很容易地以 Markdown 語法撰寫 Markdown 語法相關的文件。
<h3 id="hr">分隔線</h3>
你可以在一行中用三個或以上的星號、減號、底線來建立一個分隔線，行內不能有其他東西。你也可以在星號中間插入空白。下面每種寫法都可以建立分隔線：
? ?* * *
? ?***
? ?*****
? ?- - -
? ?---------------------------------------
* * *
<h2 id="span">區段元素</h2>
<h3 id="link">連結</h3>
Markdown 支援兩種形式的連結語法： *行內*和*參考*兩種形式。
不管是哪一種，連結的文字都是用 [方括號] 來標記。
要建立一個行內形式的連結，只要在方塊括號後面馬上接著括號並插入網址連結即可，如果你還想要加上連結的 title 文字，只要在網址後面，用雙引號把 title 文字包起來即可，例如：
? ?This is [an example](http://example.com/ "Title") inline link.
? ?[This link](http://example.net/) has no title attribute.
會產生：
? ?<p>This is <a title="Title">
? ?an example</a> inline link.</p>
? ?<p><a >This link</a> has no
? ?title attribute.</p>
如果你是要連結到同樣主機的資源，你可以使用相對路徑：
? ?See my [About](/about/) page for details. ?
參考形式的連結使用另外一個方括號接在連結文字的括號後面，而在第二個方括號裡面要填入用以辨識連結的標籤：
? ?This is [an example][id] reference-style link.
你也可以選擇性地在兩個方括號中間加上空白：
? ?This is [an example] [id] reference-style link.
接著，在文件的任意處，你可以把這個標籤的連結內容定義出來：
? ?[id]: http://example.com/ ?"Optional Title Here"
連結定義的形式為：
* ? 方括號，裡面輸入連結的辨識用標籤
* ? 接著一個冒號
* ? 接著一個以上的空白或 tab
* ? 接著連結的網址
* ? 選擇性地接著 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 會忽略單引號包起來的連結 title。
連結網址也可以用方括號包起來：
? ?[id]: <http://example.com/> ?"Optional Title Here"
你也可以把 title 屬性放到下一行，也可以加一些縮排，網址太長的話，這樣會比較好看：
? ?[id]: http://example.com/longish/path/to/resource/here
? ? ? ?"Optional Title Here"
網址定義只有在產生連結的時候用到，並不會直接出現在文件之中。
連結辨識標籤可以有字母、數字、空白和標點符號，但是並*不*區分大小寫，因此下面兩個連結是一樣的：
[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/
連結的定義可以放在文件中的任何一個地方，我比較偏好直接放在連結出現段落的後面，你也可以把它放在文件最後面，就像是註解一樣。
下面是一個參考式連結的範例：
? ?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
