...
下面這個是針對代碼區塊只有指定程式語言屬性的簡便形式：
```haskell
qsort [] = []
```
這與下面這行的效果是相同的：
``` {.haskell}
qsort [] = []
```
要取消所有語法高亮，使用 `--no-highlight` 選項。要設定語法高亮的配色，則使用 `--highlight-style`。
行區塊
-----------
**Extension: `line_blocks`**
行區塊是一連串以豎線 (`|`) 加上一個空格所構成的連續行。行與行間的區隔在輸出時將會以原樣保留，行首的空白字元數目也一樣會被保留；反之，這些行將會以 markdown 的格式處理。這個語法在輸入詩句或地址時很有幫助。
| The limerick packs laughs anatomical
| In space that is quite economical.
| But the good ones I've seen
| So seldom are clean
| And the clean ones so seldom are comical
| 200 Main St.
| Berkeley, CA 94718
如果有需要的話，書寫時也可以將完整一行拆成多行，但後續行必須以空白作為開始。下面範例的前兩行在輸出時會被視為一整行：
| The Right Honorable Most Venerable and Righteous Samuel L.
Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718
這是從 [reStructuredText] 借來的語法。
清單
-----
### 無序清單 ###
無序清單是以項目符號作列舉的清單。每條項目都以項目符號 (`*`, `+` 或 `-`) 作開頭。下面是個簡單的例子：
* one
* two
* three
這會產生一個「緊湊」清單。如果你想要一個「寬鬆」清單，也就是說以段落格式處理每個項目內的文字內容，那麼只要在每個項目間加上空白行即可：
* one
* two
* three
項目符號不能直接從行首最左邊處輸入，而必須以一至三個空白字元作縮進。項目符號後必須跟著一個空白字元。
清單項目中的接續行，若與該項目的第一行文字對齊（在項目符號之後），看上去會較為美觀：
* here is my first
list item.
* and my second.
但 markdown 也允許以下「偷懶」的格式：
* here is my first
list item.
* and my second.
### 四個空白規則 ###
一個清單項目可以包含多個段落以及其他區塊等級的內容。然而，後續的段落必須接在空白行之後，並且以四個空白或一個 tab 作縮進。因此，如果項目裡第一個段落與後面段落對齊的話（也就是項目符號前置入兩個空白），看上去會比較整齊美觀：
* First paragraph.
Continued.
* Second paragraph. With a code block, which must be indented
eight spaces:
{ code }
清單項目也可以包含其他清單。在這情況下前置的空白行是可有可無的。嵌套清單必須以四個空白或一個 tab 作縮進：
* fruits
+ apples
- macintosh
- red delicious
+ pears
+ peaches
* vegetables
+ brocolli
+ chard
上一節提到，markdown 允許你以「偷懶」的方式書寫，項目的接續行可以不和第一行對齊。不過，如果一個清單項目中包含了多個段落或是其他區塊元素，那麼每個元素的第一行都必須縮進對齊。
+ A lazy, lazy, list
item.
+ Another one; this looks
bad but is legal.
Second paragraph of second
list item.
**注意：**儘管針對接續段落的「四個空白規則」是出自於官方的 [markdown syntax guide]，但是作為對應參考用的 `Markdown.pl` 實作版本中並未遵循此一規則。所以當輸入時若接續段落的縮進少於四個空白時，pandoc 所輸出的結果會與 `Markdown.pl` 的輸出有所出入。
在 [markdown syntax guide] 中並未明確表示「四個空白規則」是否一體適用於 **所有** 位於清單項目裡的區塊元素上；規範文件中只提及了段落與代碼區塊。但文件暗示了此規則適用於所有區塊等級的內容（包含嵌套清單），並且 pandoc 以此方向進行解讀與實作。
[markdown syntax guide]:
http://daringfireball.net/projects/markdown/syntax#list
### 有序清單 ###
有序清單與無序清單相類似，唯一的差別在於清單項目是以列舉編號作開頭，而不是項目符號。
在原始 markdown 中，列舉編號是阿拉伯數字後面接著一個句點與空白。數字本身代表的數值會被忽略，因此下面兩個清單並無差別：
1. one
2. two
3. three
上下兩個清單的輸出是相同的。
5. one
7. two
1. three
**Extension: `fancy_lists`**
與原始 markdown 不同的是，Pandoc 除了使用阿拉伯數字作為有序清單的編號外，也可以使用大寫或小寫的英文字母，以及羅馬數字。清單標記可以用括號包住，也可以單獨一個右括號，抑或是句號。如果清單標記是大寫字母接著一個句號，句號後請使用至少兩個空白字元。[^2]
[^2]: 之所以有這條規則，主要是要避免以人名頭文字縮寫作為開頭的段落所帶來的混淆，像是
B. Russell was an English philosopher.
這樣就不會被當作清單項目了。
這條規則並不會避免以下
(C) 2007 Joe Smith
這樣的敘述被解釋成清單項目。在這情形下，可以使用反斜線：
(C\) 2007 Joe Smith
**Extension: `startnum`**
除了清單標記外，Pandoc 也能判讀清單的起始編號，這兩項資訊都會保留於輸出格式中。舉例來說，下面的輸入可以產生一個從編號 9 開始，以單括號為編號標記的清單，底下還跟著一個小寫羅馬數字的子清單：
9) Ninth
10) Tenth
11) Eleventh
i. subone
ii. subtwo
iii. subthree
當遇到不同形式的清單標記時，Pandoc 會重新開始一個新的清單。所以，以下的輸入會產生三份清單：
(2) Two
(5) Three
1. Four
* Five
如果需要預設的有序清單標記符號，可以使用 `#.`：
#. one
#. two
#. three
### 定義清單 ###
**Extension: `definition_lists`**
Pandoc 支援定義清單，其語法的靈感來自於 [PHP Markdown Extra] 以及 [reStructuredText]：[^3]
Term 1
: Definition 1
Term 2 with *inline markup*
: Definition 2
{ some code, part of Definition 2 }
Third paragraph of definition 2.
每個專有名詞 (term) 都必須單獨存在於一行，後面可以接著一個空白行，也可以省略，但一定要接上一或多筆定義內容。一筆定義需由一個冒號或波浪線作開頭，可以接上一或兩個空白作為縮進。定義本身的內容主體（包括接在冒號或波浪線後的第一行）應該以四個空白縮進。一個專有名詞可以有多個定義，而每個定義可以包含一或多個區塊元素（段落、代碼區塊、清單等），每個區塊元素都要縮進四個空白或一個 tab。
如果你在定義內容後面留下空白行（如同上面的範例），那麼該段定義會被當作段落處理。在某些輸出格式中，這意謂著成對的專有名詞與定義內容間會有較大的空白間距。在定義與定義之間，以及定義與下個專有名詞間不要留空白行，即可產生一個比較緊湊的定義清單：
Term 1
~ Definition 1
Term 2
~ Definition 2a
~ Definition 2b
[^3]: [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html) 對於 markdown 的建議也同時影響了我。
[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
### 編號範例清單 ###
**Extension: `example_lists`**
這個特別的清單標記 `@` 可以用來產生連續編號的範例清單。清單中第一個以 `@` 標記的項目會被編號為 '1'，接著編號為 '2'，依此類推，直到文件結束。範例項目的編號不會侷限於單一清單中，而是文件中所有以 `@` 為標記的項目均會次序遞增其編號，直到最後一個。舉例如下：
(@) My first example will be numbered (1).
(@) My second example will be numbered (2).
Explanation of examples.
(@) My third example will be numbered (3).
編號範例可以加上標籤，並且在文件的其他地方作參照：
(@good) This is a good example.
As (@good) illustrates, ...
標籤可以是由任何英文字母、底線或是連字符號所組成的字串。
### 緊湊與寬鬆清單 ###
在與清單相關的「邊界處理」上，Pandoc 與 `Markdown.pl` 有著不同的處理結果。考慮如下代碼：
+ First
+ Second:
- Fee
- Fie
- Foe
+ Third
Pandoc 會將以上清單轉換為「緊湊清單」（在 "First", "Second" 或 "Third" 之中沒有 `` 標籤），而 markdown 則會在 "Second" 與 "Third" （但不包含 "First"）裡面置入 `
` 標籤，這是因為 "Third" 之前的空白行而造成的結果。Pandoc 依循著一個簡單規則：如果文字後面跟著空白行，那麼就會被視為段落。既然 "Second" 後面是跟著一個清單，而非空白行，那麼就不會被視為段落了。至於子清單的後面是不是跟著空白行，那就無關緊要了。（注意：即使是設定為 `markdown_strict` 格式，Pandoc 仍是依以上方式處理清單項目是否為段落的判定。這個處理方式與 markdown 官方語法規範裡的描述一致，然而卻與 `Markdown.pl` 的處理不同。） ### 結束一個清單 ### 如果你在清單之後放入一個縮排的代碼區塊，會有什麼結果？ - item one - item two { my code block } 問題大了！這邊 pandoc（其他的 markdown 實作也是如此）會將 `{ my code block }` 視為 `item two` 這個清單項目的第二個段落來處理，而不會將其視為一個代碼區塊。 要在 `item two` 之後「切斷」清單，你可以插入一些沒有縮排、輸出時也不可見的內容，例如 HTML 的註解： - item one - item two { my code block } 當你想要兩個各自獨立的清單，而非一個大且連續的清單時，也可以運用同樣的技巧： 1. one 2. two 3. three 1. uno 2. dos 3. tres 分隔線 ---------------- 一行中若包含三個以上的 `*`, `-` 或 `_` 符號（中間可以以空白字元分隔），則會產生一條分隔線： * * * * --------------- 表格 ------ 有四種表格的形式可以使用。前三種適用於等寬字型的編輯環境，例如 Courier。第四種則不需要直行的對齊，因此可以在比例字型的環境下使用。 ### 簡單表格 **Extension: `simple_tables`, `table_captions`** 簡單表格看起來像這樣子： Right Left Center Default ------- ------ ---------- ------- 12 12 12 12 123 123 123 123 1 1 1 1 Table: Demonstration of simple table syntax. 表頭與資料列分別以一行為單位。直行的對齊則依照表頭的文字和其底下虛線的相對位置來決定：[^4] - 如果虛線與表頭文字的右側有切齊，而左側比表頭文字還長，則該直行為靠右對齊。 - 如果虛線與表頭文字的左側有切齊，而右側比表頭文字還長，則該直行為靠左對齊。 - 如果虛線的兩側都比表頭文字長，則該直行為置中對齊。 - 如果虛線與表頭文字的兩側都有切齊，則會套用預設的對齊方式（在大多數情況下，這將會是靠左對齊）。 [^4]: 這個方案是由 Michel Fortin 在 [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html) 的討論中所提出。 表格底下必須接著一個空白行，或是一行虛線後再一個空白行。表格標題為可選的（上面的範例中有出現）。標題需是一個以 `Table:` （或單純只有 `:`）開頭作為前綴的段落，輸出時前綴的這部份會被去除掉。表格標題可以放在表格之前或之後。 表頭也可以省略，在省略表頭的情況下，表格下方必須加上一行虛線以清楚標明表格的範圍。例如： ------- ------ ---------- ------- 12 12 12 12 123 123 123 123 1 1 1 1 ------- ------ ---------- ------- 當省略表頭時，直行的對齊會以表格內容的第一行資料列決定。所以，以上面的表格為例，各直行的對齊依序會是靠右、靠左、置中以及靠右對齊。 ### 多行表格 **Extension: `multiline_tables`, `table_captions`** 多行表格允許表頭與表格資料格的文字能以複數行呈現（但不支援橫跨多欄或縱跨多列的資料格）。以下為範例： ------------------------------------------------------------- Centered Default Right Left Header Aligned Aligned Aligned ----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. ------------------------------------------------------------- Table: Here's the caption. It, too, may span multiple lines. 看起來很像簡單表格，但兩者間有以下差別： - 在表頭文字之前，必須以一列虛線作為開頭（除非有省略表頭）。 - 必須以一列虛線作為表格結尾，之後接一個空白行。 - 資料列與資料列之間以空白行隔開。 在多行表格中，表格分析器會計算各直行的欄寬，並在輸出時盡可能維持各直行在原始文件中的相對比例。因此，要是你覺得某些欄位在輸出時不夠寬，你可以在 markdown 的原始檔中加寬一點。 和簡單表格一樣，表頭在多行表格中也是可以省略的： ----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. ----------- ------- --------------- ------------------------- : Here's a multiline table without headers. 多行表格中可以單只包含一個資料列，但該資料列之後必須接著一個空白行（然後才是標示表格結尾的一行虛線）。如果沒有此空白行，此表格將會被解讀成簡單表格。 ### 格框表格 **Extension: `grid_tables`, `table_captions`** 格框表格看起來像這樣： : Sample grid table. +---------------+---------------+--------------------+ | Fruit | Price | Advantages | +===============+===============+====================+ | Bananas | $1.34 | - built-in wrapper | | | | - bright color | +---------------+---------------+--------------------+ | Oranges | $2.10 | - cures scurvy | | | | - tasty | +---------------+---------------+--------------------+ 以 `=` 串成的一行區分了表頭與表格本體，這在沒有表頭的表格中也是可以省略的。在格框表格中的資料格可以包含任意的區塊元素（複數段落、代碼區塊、清單等等）。不支援對齊，也不支援橫跨多欄或縱跨多列的資料格。格框表格可以在 [Emacs table mode] 下輕鬆建立。 [Emacs table mode]: http://table.sourceforge.net/ ### 管線表格 **Extension: `pipe_tables`, `table_captions`** 管線表格看起來像這樣： | Right | Left | Default | Center | |------:|:-----|---------|:------:| | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 | : Demonstration of simple table syntax. 這個語法與 [PHP markdown extra 中的表格語法][the same as in PHP markdown extra] 相同。開始與結尾的管線字元是可選的，但各直行間則必須以管線區隔。上面範例中的冒號表明了對齊方式。表頭可以省略，但表頭下的水平虛線必須保留，因為虛線上定義了資料欄的對齊方式。 因為管線界定了各欄之間的邊界，表格的原始碼並不需要像上面例子中各欄之間保持直行對齊。所以，底下一樣是個完全合法（雖然醜陋）的管線表格： fruit| price -----|-----: apple|2.05 pear|1.37 orange|3.09 管線表格的資料格不能包含如段落、清單之類的區塊元素，也不能包含複數行文字。 [the same as in PHP markdown extra]: http://michelf.ca/projects/php-markdown/extra/#table 注意：Pandoc 也可以看得懂以下形式的管線表格，這是由 Emacs 的 orgtbl-mod 所繪製： | One | Two | |-----+-------| | my | table | | is | nice | 主要的差別在於以 `+` 取代了部分的 `|`。其他的 orgtbl 功能並未支援。如果要指定非預設的直行對齊形式，你仍然需要在上面的表格中自行加入冒號。 文件標題區塊 ----------- （譯註：本節中提到的「標題」均指 Title，而非 Headers） **Extension: `pandoc_title_block`** 如果檔案以文件標題（Title）區塊開頭 % title % author(s) (separated by semicolons) % date 這部份將不會作為一般文字處理，而會以書目資訊的方式解析。（這可用在像是單一 LaTeX 或是 HTML 輸出文件的書名上。）這個區塊僅能包含標題，或是標題與作者，或是標題、作者與日期。如果你只想包含作者卻不想包含標題，或是只有標題與日期而沒有作者，你得利用空白行： % % Author % My title % % June 15, 2006 標題可以包含多行文字，但接續行必須以空白字元開頭，像是： % My title on multiple lines 如果文件有多個作者，作者也可以分列在不同行並以空白字元作開頭，或是以分號間隔，或是兩者並行。所以，下列各種寫法得到的結果都是相同的： % Author One Author Two % Author One; Author Two % Author One; Author Two 日期就只能寫在一行之內。 所有這三個 metadata 欄位都可以包含標準的行內格式（斜體、連結、腳註等等）。 文件標題區塊一定會被分析處理，但只有在 `--standaline` (`-s`) 選項被設定時才會影響輸出內容。在輸出 HTML 時，文件標題會出現的地方有兩個：一個是在文件的 `
` 區塊裡－－這會顯示在瀏覽器的視窗標題上－－另外一個是文件的 `` 區塊最前面。位於 `` 裡的文件標題可以選擇性地加上前綴文字（透過 `--title-prefix` 或 `-T` 選項）。而在 `` 裡的文件標題會以 H1 元素呈現，並附帶 "title" 類別 (class)，這樣就能藉由 CSS 來隱藏顯示或重新定義格式。如果以 `-T` 選項指定了標題前綴文字，卻沒有設定文件標題區塊裡的標題，那麼前綴文字本身就會被當作是 HTML 的文件標題。 而 man page 的輸出器會分析文件標題區塊的標題行，以解出標題、man page section number，以及其他頁眉 (header) 頁腳 (footer) 所需要的資訊。一般會假設標題行的第一個單字為標題，標題後也許會緊接著一個以括號包住的單一數字，代表 section number（標題與括號之間沒有空白）。在此之後的其他文字則為頁腳與頁眉文字。頁腳與頁眉文字之間是以單獨的一個管線符號 (`|`) 作為區隔。所以， % PANDOC(1) 將會產生一份標題為 `PANDOC` 且 section 為 1 的 man page。 % PANDOC(1) Pandoc User Manuals 產生的 man page 會再加上 "Pandoc User Manuals" 在頁腳處。 % PANDOC(1) Pandoc User Manuals | Version 4.0 產生的 man page 會再加上 "Version 4.0" 在頁眉處。 反斜線跳脫字元 ----------------- **Extension: `all_symbols_escapable`** 除了在代碼區塊或行內代碼之外，任何標點符號或空白字元前面只要加上一個反斜線，都能使其保留字面原義，而不會進行格式的轉義解讀。因此，舉例來說，下面的寫法 *\*hello\** 輸出後會得到 *hello* 而不是 hello 這條規則比原始的 markdown 規則來得好記許多，原始規則中，只有以下字元才有支援反斜線跳脫，不作進一步轉義： \`*_{}[]()>#+-.! （然而，如果使用了 `markdown_strict` 格式，那麼就會採用原始的 markdown 規則） 一個反斜線之後的空白字元會被解釋為不斷行的空白 (nonbreaking space)。這在 TeX 的輸出中會顯示為 `~`，而在 HTML 與 XML 則是顯示為 `\ ` 或 `\ `。 一個反斜線之後的換行字元（例如反斜線符號出現在一行的最尾端）則會被解釋為強制換行。這在 TeX 的輸出中會顯示為 `\\`，而在 HTML 裡則是 `