% [Pandoc's Markdown 語法中文翻譯][home] % by John MacFarlane; Translated by [Tzeng Yuxio](http://tzengyuxio.me) [home]: http://pages.tzengyuxio.me/pandoc/ 前言 -------- 這份文件是 [Pandoc][] 版本 Markdown 語法的中文翻譯。Pandoc 本身是由 [John MacFarlane][] 所開發的文件轉換工具,可以在 HTML, Markdown, PDF, TeX...等等格式之間進行轉換。有許多喜歡純文字編輯的人,利用 Pandoc 來進行論文的撰寫或投影片製作。但除了轉換的功能外,Pandoc 所定義的 Markdown 擴充語法也是這套工具的一大亮點,在 Pandoc 的官方使用說明文件中,光是其針對 Markdown 格式的擴充就佔了整整一半左右的篇幅。 本文件翻譯自 [Pandoc - Pandoc User’s Guide][userguide] 中的 "Pandoc's markdown" 一節。你可以看看[這份文件的原始檔][source]、產生文件[所使用的 HTML 範本][template],以及[轉換時的命令參數][script]。 [John MacFarlane]: http://johnmacfarlane.net/ [pandoc]: http://johnmacfarlane.net/pandoc/ [userguide]: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown [source]: https://raw.github.com/tzengyuxio/pages/gh-pages/pandoc/pandoc.markdown [template]: https://github.com/tzengyuxio/pages/blob/gh-pages/pandoc/pm-template.html5 [script]: https://github.com/tzengyuxio/pages/blob/gh-pages/pandoc/convert.sh 以下翻譯開始。 ---- Pandoc's markdown ================= 與 John Gruber 的 原始 [markdown] 相比,Pandoc 版本的 markdown 在語法上有額外的擴充與些許的修正。這份文件解釋了這些語法,並指出其與原始 markdown 的差異所在。除非特別提到,不然這些差異均可藉由使用 `markdown_strict` 而非 `markdown` 的格式來關閉。單獨一項擴充也可透過 `+EXTENSION` 或 `-EXTENSION` 的方式來開啟或關閉。例如,`markdown_strict+footnotes` 表示加上腳註擴充的原始 markdown,而 `markdown-footnotes-pipe_tables` 則是拿掉了腳註與管線表格擴充的 pandoc markdown。 哲學 ---------- Markdown 是針對易於書寫與閱讀的目標而設計的,特別是在易於閱讀這點上尤為重要: > 一份 Markdown 格式的文件應該要能以純文字形式直接發表,並且一眼看過去不存在任何標記用的標籤或格式指令。 > [John Gruber](http://daringfireball.net/projects/markdown/syntax#philosophy) 這項原則同樣也是 pandoc 在制訂表格、腳註以及其他擴充的語法時,所依循的規範。 然而,pandoc 的目標與原始 markdown 的最初目標有著方向性的不同。在 markdown 原本的設計中,HTML 是其主要輸出對象;然而 pandoc 則是針對多種輸出格式而設計。因此,雖然 pandoc 同樣也允許直接嵌入 HTML 標籤,但並不鼓勵這樣的作法,取而代之的是 pandoc 提供了許多非 HTML 的方式,來讓使用者輸入像是定義清單、表格、數學公式以及腳註等諸如此類的重要文件元素。 段落 ---------- 一個段落指的是一行以上的文字,跟在一行以上的空白行之後。換行字元會被當作是空白處理,因此你可以依自己喜好排列段落文字。如果你需要強制換行,在行尾放上兩個以上的空白字元即可。 **Extension: `escaped_line_breaks`** 一個反斜線後跟著一個換行字元,同樣也有強制換行的效果。 標題 ------- 有兩種不同形式的標題語法,Setext 以及 atx。 ### Setext 風格標題 ### Setext 風格的標題是由一行文字底下接著一行 `=` 符號(用於一階標題)或 `-` 符號(用於二階標題)所構成: A level-one header ================== A level-two header ------------------ 標題的文字可以包含行內格式,例如強調(見下方 [行內格式] 一節)。 ### Atx 風格標題 ### Atx 風格的標題是由一到六個 `#` 符號以及一行文字所組成,你可以在文字後面加上任意數量的 `#` 符號。由行首起算的 `#` 符號數量決定了標題的階層: ## A level-two header ### A level-three header ### 如同 setext 風格標題,這裡的標題文字同樣可包含行內格式: # A level-one header with a [link](/url) and *emphasis* **Extension: `blank_before_header`** 原始 markdown 語法在標題之前並不需要預留空白行。Pandoc 則需要(除非標題位於文件最開始的地方)。這是因為以 `#` 符號開頭的情況在一般文字段落中相當常見,這會導致非預期的標題。例如下面的例子: I like several of their flavors of ice cream: #22, for example, and #5. ### HTML, LaTeX 與 ConTeXt 的標題識別符 ### **Extension: `header_attributes`** 在標題文字所在行的行尾,可以使用以下語法為標題加上屬性: {#identifier .class .class key=value key=value} 雖然這個語法也包含加入類別 (class) 以及鍵/值形式的屬性 (attribute),但目前只有識別符 (identifier/ID) 在輸出時有實際作用(且只在部分格式的輸出,包括:HTML, LaTeX, ConTeXt, Textile, AsciiDoc)。舉例來說,下面是將標題加上 `foo` 識別符的幾種方法: # My header {#foo} ## My header ## {#foo} My other header {#foo} --------------- (此語法與 [PHP Markdown Extra] 相容。) 具有 `unnumbered` 類別的標題將不會被編號,即使 `--number-sections` 的選項是開啟的。單一連字符號 (`-`) 等同於 `.unnumbered`,且更適用於非英文文件中。因此, # My header {-} 與下面這行是等價的 # My header {.unnumbered} **Extension: `auto_identifiers`** 沒有明確指定 ID(識別符)的標題將會依據其標題文字,自動指派一個獨一無二的 ID。由標題文字推導 ID 的規則如下: - 移除所有格式,連結等。 - 移除所有標點符號,除了底線、連字符號與句號。 - 以連字符號取代所有空白與換行字元。 - 將所有英文字母轉為小寫。 - 移除第一個字元前的所有內容(ID 不能以數字或標點符號開頭)。 - 如果剩下為空字串,則使用 `section` 作為 ID。 以下是一些範例, Header Identifier ------------------------------- ---------------------------- Header identifiers in HTML `header-identifiers-in-html` *Dogs*?--in *my* house? `dogs--in-my-house` [HTML], [S5], or [RTF]? `html-s5-or-rtf` 3. Applications `applications` 33 `section` 在大多數情況下,這些規則應該讓人能夠直接從標題文字推導出 ID。唯一的例外是當有多個標題具有同樣文字的情況;在這情況下,第一個標題的 ID 仍舊是透過以上規則推導而得;第二個則是在同樣 ID 後加上 `-1`;第三個加上 `-2`;以此類推。 在開啟 `--toc|--table-of-contents` 的選項時,這些 ID 是用來產生目錄 (Table of Contents) 所需的頁面連結。此外,這些 ID 也提供了一個簡便的方式來輸入跳到指定章節的連結。一個以 ID 產生的連結,其使用的語法看起來就像下面的例子: See the section on [header identifiers](#header-identifiers-in-html-latex-and-context). 然而要注意的一點是,只有在以 HTML、LaTeX 與 ConTeXt 格式輸出時,才能以這種方式產生對應的章節連結。 如果指定了 `--section-divs` 選項,則每一個小節都會以 `div` 標籤包住(或是 `section` 標籤,如果有指定 `--html5` 選項的話),並且 ID 會被附加在用來包住小節的 `
...
下面這個是針對代碼區塊只有指定程式語言屬性的簡便形式:
```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 裡則是 `