Pandoc`s Markdown 语法中文翻译

前言

這份文件是 Pandoc 版本 Markdown語法的中文翻譯。Pandoc 本身是由 John MacFarlane所開發的文件轉換工具,可以在HTML, Markdown, PDF,TeX…等等格式之間進行轉換。有許多喜歡純文字編輯的人,利用 Pandoc來進行論文的撰寫或投影片製作。但除了轉換的功能外,Pandoc 所定義的 Markdown擴充語法也是這套工具的一大亮點,在 Pandoc 的官方使用說明文件中,光是其針對Markdown 格式的擴充就佔了整整一半左右的篇幅。

本文件翻譯自 Pandoc - Pandoc User’sGuide 中的“Pandoc’s markdown” 一節。你可以看看這份文件的原始檔、產生文件所使用的HTML範本,以及轉換時的命令參數。以下翻譯開始。

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

這項原則同樣也是 pandoc 在制訂表格、腳註以及其他擴充的語法時,所依循的規範。

然而,pandoc 的目標與原始 markdown 的最初目標有著方向性的不同。在 markdown 原本的設計中,HTML 是其主要輸出對象;然而 pandoc 則是針對多種輸出格式而設計。因此,雖然 pandoc 同樣也允許直接嵌入 HTML 標籤,但並不鼓勵這樣的作法,取而代之的是 pandoc 提供了許多非 HTML 的方式,來讓使用者輸入像是定義清單、表格、數學公式以及腳註等諸如此類的重要文件元素。

段落

一個段落指的是一行以上的文字,跟在一行以上的空白行之後。換行字元會被當作是空白處理,因此你可以依自己喜好排列段落文字。如果你需要強制換行,在行尾放上兩個以上的空白字元即可。

Extension: escaped_line_breaks

一個反斜線後跟著一個換行字元,同樣也有強制換行的效果。

標題

有兩種不同形式的標題語法,Setext 以及 atx。

Setext 風格標題

Setext 風格的標題是由一行文字底下接著一行 = 符號(用於一階標題)或 - 符號(用於二階標題)所構成:

1
2
3
4
5
A level-one header
==================

A level-two header
------------------

標題的文字可以包含行內格式,例如強調(見下方 行內格式 一節)。

Atx 風格標題

Atx 風格的標題是由一到六個 # 符號以及一行文字所組成,你可以在文字後面加上任意數量的 # 符號。由行首起算的 # 符號數量決定了標題的階層:

1
2
3
## A level-two header

### A level-three header ###

如同 setext 風格標題,這裡的標題文字同樣可包含行內格式:

1
# A level-one header with a [link](/url) and *emphasis*

Extension: blank_before_header

原始 markdown 語法在標題之前並不需要預留空白行。Pandoc 則需要(除非標題位於文件最開始的地方)。這是因為以 # 符號開頭的情況在一般文字段落中相當常見,這會導致非預期的標題。例如下面的例子:

1
2
I like several of their flavors of ice cream:
#22, for example, and #5.

HTML, LaTeX 與 ConTeXt 的標題識別符

Extension: header_attributes

在標題文字所在行的行尾,可以使用以下語法為標題加上屬性:

1
{#identifier .class .class key=value key=value}

雖然這個語法也包含加入類別 (class) 以及鍵/值形式的屬性 (attribute),但目前只有識別符 (identifier/ID) 在輸出時有實際作用(且只在部分格式的輸出,包括:HTML, LaTeX, ConTeXt, Textile, AsciiDoc)。舉例來說,下面是將標題加上 foo 識別符的幾種方法:

1
2
3
4
5
6
# My header {#foo}

## My header ## {#foo}

My other header {#foo}
---------------

(此語法與 PHP Markdown Extra 相容。)

具有 unnumbered 類別的標題將不會被編號,即使 --number-sections 的選項是開啟的。單一連字符號 (-) 等同於 .unnumbered,且更適用於非英文文件中。因此,

1
# My header {-}

與下面這行是等價的

1
# 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 產生的連結,其使用的語法看起來就像下面的例子:

1
2
See the section on
[header identifiers](#header-identifiers-in-html-latex-and-context).

然而要注意的一點是,只有在以 HTML、LaTeX 與 ConTeXt 格式輸出時,才能以這種方式產生對應的章節連結。

如果指定了 --section-divs 選項,則每一個小節都會以 div 標籤包住(或是 section 標籤,如果有指定 --html5 選項的話),並且 ID 會被附加在用來包住小節的 <div>(或是 <section>)標籤,而非附加在標題上。這使得整個小節都可以透過 javascript 來操作,或是採用不同的 CSS 設定。

Extension: implicit_header_references

Pandoc 假設每個標題都定義了其參考連結,因此,相較於以下的連結語法

1
[header identifiers](#header-identifiers-in-html)

你也可以單純只寫

1
[header identifiers]

1
[header identifiers][]

1
[the section on header identifiers][header identifiers]

如果有多個標題具有同樣文字,對應的參考只會連結到第一個符合的標題,這時若要連結到其他符合的標題,就必須以先前提到的方式,明確指定連結到該標題的 ID。

與其他一般參考連結不同的是,這些參考連結是大小寫有別的。

注意:如果你有明確定義了任何一個標題的標示符,那麼選項 implicit_header_references 就沒有作用。

區塊引言

Markdown 使用 email 的習慣來建立引言區塊。一個引言區塊可以由一或多個段落或其他的區塊元素(如清單或標題)組成,並且其行首均是由一個 > 符號加上一個空白作為開頭。(> 符號不一定要位在該行最左邊,但也不能縮進超過三個空白)。

1
2
3
4
5
> This is a block quote. This
> paragraph has two lines.
>
> 1. This is a list inside a block quote.
> 2. Second item.

有一個「偷懶」的形式:你只需要在引言區塊的第一行行首輸入 > 即可,後面的行首可以省略符號:

1
2
3
4
5
> This is a block quote. This
paragraph has two lines.

> 1. This is a list inside a block quote.
2. Second item.

由於區塊引言可包含其他區塊元素,而區塊引言本身也是區塊元素,所以,引言是可以嵌套入其他引言的。

1
2
3
> This is a block quote.
>
> > A block quote within a block quote.

Extension: blank_before_blockquote

原始 markdown 語法在區塊引言之前並不需要預留空白行。Pandoc 則需要(除非區塊引言位於文件最開始的地方)。這是因為以 > 符號開頭的情況在一般文字段落中相當常見(也許由於斷行所致),這會導致非預期的格式。因此,除非是指定為 markdown_strict 格式,不然以下的語法在 pandoc 中將不會產生出嵌套區塊引言:

1
2
> This is a block quote.
>> Nested.

字面(代碼)區塊

縮進代碼區塊

一段以四個空白(或一個 tab)縮進的文字區塊會被視為字面區塊 (Verbatim Block):換句話說,特殊字元並不會轉換為任何格式,單純只以字面形式呈現,而所有的空白與換行也都會被保留。例如,

1
2
3
if (a > 3) {
moveShip(5 * gravity, DOWN);
}

位於行首的縮排(四個空白或一個 tab)並不會被視為字面區塊的一部分,因此在輸出時會被移除掉。

注意:在字面文字之間的空白行並不需要也以四個空白字元做開頭。

圍欄代碼區塊

Extension: fenced_code_blocks

除了標準的縮進代碼區塊外,Pandoc 也支援了圍欄 (fenced) 代碼區塊的語法。這區塊需以包含三個以上波浪線 (~) 或反引號 (`) 的一行作為開始,並以同樣符號且至少同樣長度的一行作為結束。所有介於開始與結束之間的文字行都會視為代碼。不需要額外的縮進:

1
2
3
4
5
​~~~~~~~
if (a > 3) {
moveShip(5 * gravity, DOWN);
}
​~~~~~~~

如同一般的代碼區塊,圍欄代碼區塊與其前後的文字之間必須以空白行作間隔。

如果代碼本身也包含了一整行的波浪線或反引號,那麼只要在區塊首尾處使用更長的波浪線或反引號即可:

1
2
3
4
5
​~~~~~~~~~~~~~~~~
​~~~~~~~~~~
code including tildes
​~~~~~~~~~~
​~~~~~~~~~~~~~~~~

你也可以選擇性地使用以下語法附加屬性到代碼區塊上:

1
2
3
4
5
​~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
​~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

這裡的 mycode 為 ID,haskellnumberLines 是類別,而 startsFrom 則是值為 100 的屬性。有些輸出格式可以利用這些資訊來作語法高亮。目前有使用到這些資訊的輸出格式僅有 HTML 與 LaTeX。如果指定的輸出格式及語言類別有支援語法高亮,那麼上面那段代碼區塊將會以高亮並帶有行號的方式呈現。(要查詢支援的程式語言清單,可在命令列輸入 pandoc --version。)反之若無支援,則上面那段代碼區塊則會以下面的形式呈現:

1
2
3
4
5
<pre id="mycode" class="haskell numberLines" startFrom="100">
<code>
...
</code>
</pre>

下面這個是針對代碼區塊只有指定程式語言屬性的簡便形式:

1
2
3
​```haskell
qsort [] = []
​```

這與下面這行的效果是相同的:

1
2
3
​``` {.haskell}
qsort [] = []
​```

要取消所有語法高亮,使用 --no-highlight 選項。要設定語法高亮的配色,則使用 --highlight-style

行區塊

Extension: line_blocks

行區塊是一連串以豎線 (|) 加上一個空格所構成的連續行。行與行間的區隔在輸出時將會以原樣保留,行首的空白字元數目也一樣會被保留;反之,這些行將會以 markdown 的格式處理。這個語法在輸入詩句或地址時很有幫助。

1
2
3
4
5
6
7
8
| 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

如果有需要的話,書寫時也可以將完整一行拆成多行,但後續行必須以空白作為開始。下面範例的前兩行在輸出時會被視為一整行:

1
2
3
4
| The Right Honorable Most Venerable and Righteous Samuel L.
Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718

這是從 reStructuredText 借來的語法。

清單

無序清單

無序清單是以項目符號作列舉的清單。每條項目都以項目符號 (*, +-) 作開頭。下面是個簡單的例子:

1
2
3
* one
* two
* three

這會產生一個「緊湊」清單。如果你想要一個「寬鬆」清單,也就是說以段落格式處理每個項目內的文字內容,那麼只要在每個項目間加上空白行即可:

1
2
3
4
5
* one

* two

* three

項目符號不能直接從行首最左邊處輸入,而必須以一至三個空白字元作縮進。項目符號後必須跟著一個空白字元。

清單項目中的接續行,若與該項目的第一行文字對齊(在項目符號之後),看上去會較為美觀:

1
2
3
* here is my first
list item.
* and my second.

但 markdown 也允許以下「偷懶」的格式:

1
2
3
* here is my first
list item.
* and my second.

四個空白規則

一個清單項目可以包含多個段落以及其他區塊等級的內容。然而,後續的段落必須接在空白行之後,並且以四個空白或一個 tab 作縮進。因此,如果項目裡第一個段落與後面段落對齊的話(也就是項目符號前置入兩個空白),看上去會比較整齊美觀:

1
2
3
4
5
6
7
8
* First paragraph.

Continued.

* Second paragraph. With a code block, which must be indented
eight spaces:

{ code }

清單項目也可以包含其他清單。在這情況下前置的空白行是可有可無的。嵌套清單必須以四個空白或一個 tab 作縮進:

1
2
3
4
5
6
7
8
9
* fruits
+ apples
- macintosh
- red delicious
+ pears
+ peaches
* vegetables
+ brocolli
+ chard

上一節提到,markdown 允許你以「偷懶」的方式書寫,項目的接續行可以不和第一行對齊。不過,如果一個清單項目中包含了多個段落或是其他區塊元素,那麼每個元素的第一行都必須縮進對齊。

1
2
3
4
5
6
7
8
+ 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 中,列舉編號是阿拉伯數字後面接著一個句點與空白。數字本身代表的數值會被忽略,因此下面兩個清單並無差別:

1
2
3
1.  one
2. two
3. three

上下兩個清單的輸出是相同的。

1
2
3
5.  one
7. two
1. three

Extension: fancy_lists

與原始 markdown 不同的是,Pandoc 除了使用阿拉伯數字作為有序清單的編號外,也可以使用大寫或小寫的英文字母,以及羅馬數字。清單標記可以用括號包住,也可以單獨一個右括號,抑或是句號。如果清單標記是大寫字母接著一個句號,句號後請使用至少兩個空白字元。1

Extension: startnum

除了清單標記外,Pandoc 也能判讀清單的起始編號,這兩項資訊都會保留於輸出格式中。舉例來說,下面的輸入可以產生一個從編號 9 開始,以單括號為編號標記的清單,底下還跟著一個小寫羅馬數字的子清單:

1
2
3
4
5
6
 9)  Ninth
10) Tenth
11) Eleventh
i. subone
ii. subtwo
iii. subthree

當遇到不同形式的清單標記時,Pandoc 會重新開始一個新的清單。所以,以下的輸入會產生三份清單:

1
2
3
4
(2) Two
(5) Three
1. Four
* Five

如果需要預設的有序清單標記符號,可以使用 #.

1
2
3
#.  one
#. two
#. three

定義清單

Extension: definition_lists

Pandoc 支援定義清單,其語法的靈感來自於 PHP Markdown Extra 以及 reStructuredText2

1
2
3
4
5
6
7
8
9
10
11
Term 1

: Definition 1

Term 2 with *inline markup*

: Definition 2

{ some code, part of Definition 2 }

Third paragraph of definition 2.

每個專有名詞 (term) 都必須單獨存在於一行,後面可以接著一個空白行,也可以省略,但一定要接上一或多筆定義內容。一筆定義需由一個冒號或波浪線作開頭,可以接上一或兩個空白作為縮進。定義本身的內容主體(包括接在冒號或波浪線後的第一行)應該以四個空白縮進。一個專有名詞可以有多個定義,而每個定義可以包含一或多個區塊元素(段落、代碼區塊、清單等),每個區塊元素都要縮進四個空白或一個 tab。

如果你在定義內容後面留下空白行(如同上面的範例),那麼該段定義會被當作段落處理。在某些輸出格式中,這意謂著成對的專有名詞與定義內容間會有較大的空白間距。在定義與定義之間,以及定義與下個專有名詞間不要留空白行,即可產生一個比較緊湊的定義清單:

1
2
3
4
5
Term 1
~ Definition 1
Term 2
~ Definition 2a
~ Definition 2b

編號範例清單

Extension: example_lists

這個特別的清單標記 @ 可以用來產生連續編號的範例清單。清單中第一個以 @ 標記的項目會被編號為 ‘1’,接著編號為 ‘2’,依此類推,直到文件結束。範例項目的編號不會侷限於單一清單中,而是文件中所有以 @ 為標記的項目均會次序遞增其編號,直到最後一個。舉例如下:

1
2
3
4
5
6
(@)  My first example will be numbered (1).
(@) My second example will be numbered (2).

Explanation of examples.

(@) My third example will be numbered (3).

編號範例可以加上標籤,並且在文件的其他地方作參照:

1
2
3
(@good)  This is a good example.

As (@good) illustrates, ...

標籤可以是由任何英文字母、底線或是連字符號所組成的字串。

緊湊與寬鬆清單

在與清單相關的「邊界處理」上,Pandoc 與 Markdown.pl 有著不同的處理結果。考慮如下代碼:

1
2
3
4
5
6
7
+   First
+ Second:
- Fee
- Fie
- Foe

+ Third

Pandoc 會將以上清單轉換為「緊湊清單」(在 “First”, “Second” 或 “Third” 之中沒有 <p> 標籤),而 markdown 則會在 “Second” 與 “Third” (但不包含 “First”)裡面置入 <p> 標籤,這是因為 “Third” 之前的空白行而造成的結果。Pandoc 依循著一個簡單規則:如果文字後面跟著空白行,那麼就會被視為段落。既然 “Second” 後面是跟著一個清單,而非空白行,那麼就不會被視為段落了。至於子清單的後面是不是跟著空白行,那就無關緊要了。(注意:即使是設定為 markdown_strict 格式,Pandoc 仍是依以上方式處理清單項目是否為段落的判定。這個處理方式與 markdown 官方語法規範裡的描述一致,然而卻與 Markdown.pl 的處理不同。)

結束一個清單

如果你在清單之後放入一個縮排的代碼區塊,會有什麼結果?

1
2
3
4
-   item one
- item two

{ my code block }

問題大了!這邊 pandoc(其他的 markdown 實作也是如此)會將 { my code block } 視為 item two 這個清單項目的第二個段落來處理,而不會將其視為一個代碼區塊。

要在 item two 之後「切斷」清單,你可以插入一些沒有縮排、輸出時也不可見的內容,例如 HTML 的註解:

1
2
3
4
5
6
-   item one
- item two

<!-- end of list -->

{ my code block }

當你想要兩個各自獨立的清單,而非一個大且連續的清單時,也可以運用同樣的技巧:

1
2
3
4
5
6
7
8
9
1.  one
2. two
3. three

<!-- -->

1. uno
2. dos
3. tres

分隔線

一行中若包含三個以上的 *, -_ 符號(中間可以以空白字元分隔),則會產生一條分隔線:

1
2
3
*  *  *  *

---------------

表格

有四種表格的形式可以使用。前三種適用於等寬字型的編輯環境,例如 Courier。第四種則不需要直行的對齊,因此可以在比例字型的環境下使用。

簡單表格

Extension: simple_tables, table_captions

簡單表格看起來像這樣子:

1
2
3
4
5
6
7
  Right     Left     Center     Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1

Table: Demonstration of simple table syntax.

表頭與資料列分別以一行為單位。直行的對齊則依照表頭的文字和其底下虛線的相對位置來決定:3

  • 如果虛線與表頭文字的右側有切齊,而左側比表頭文字還長,則該直行為靠右對齊。

  • 如果虛線與表頭文字的左側有切齊,而右側比表頭文字還長,則該直行為靠左對齊。

  • 如果虛線的兩側都比表頭文字長,則該直行為置中對齊。

  • 如果虛線與表頭文字的兩側都有切齊,則會套用預設的對齊方式(在大多數情況下,這將會是靠左對齊)。

表格底下必須接著一個空白行,或是一行虛線後再一個空白行。表格標題為可選的(上面的範例中有出現)。標題需是一個以 Table: (或單純只有 :)開頭作為前綴的段落,輸出時前綴的這部份會被去除掉。表格標題可以放在表格之前或之後。

表頭也可以省略,在省略表頭的情況下,表格下方必須加上一行虛線以清楚標明表格的範圍。例如:

1
2
3
4
5
-------     ------ ----------   -------
12 12 12 12
123 123 123 123
1 1 1 1
------- ------ ---------- -------

當省略表頭時,直行的對齊會以表格內容的第一行資料列決定。所以,以上面的表格為例,各直行的對齊依序會是靠右、靠左、置中以及靠右對齊。

多行表格

Extension: multiline_tables, table_captions

多行表格允許表頭與表格資料格的文字能以複數行呈現(但不支援橫跨多欄或縱跨多列的資料格)。以下為範例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
-------------------------------------------------------------
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 的原始檔中加寬一點。

和簡單表格一樣,表頭在多行表格中也是可以省略的:

1
2
3
4
5
6
7
8
9
10
----------- ------- --------------- -------------------------
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

格框表格看起來像這樣:

1
2
3
4
5
6
7
8
9
10
11
: Sample grid table.

+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+===============+===============+====================+
| Bananas | $1.34 | - built-in wrapper |
| | | - bright color |
+---------------+---------------+--------------------+
| Oranges | $2.10 | - cures scurvy |
| | | - tasty |
+---------------+---------------+--------------------+

= 串成的一行區分了表頭與表格本體,這在沒有表頭的表格中也是可以省略的。在格框表格中的資料格可以包含任意的區塊元素(複數段落、代碼區塊、清單等等)。不支援對齊,也不支援橫跨多欄或縱跨多列的資料格。格框表格可以在 Emacs table mode 下輕鬆建立。

管線表格

Extension: pipe_tables, table_captions

管線表格看起來像這樣:

1
2
3
4
5
6
7
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |

: Demonstration of simple table syntax.

這個語法與 PHP markdown extra 中的表格語法 相同。開始與結尾的管線字元是可選的,但各直行間則必須以管線區隔。上面範例中的冒號表明了對齊方式。表頭可以省略,但表頭下的水平虛線必須保留,因為虛線上定義了資料欄的對齊方式。

因為管線界定了各欄之間的邊界,表格的原始碼並不需要像上面例子中各欄之間保持直行對齊。所以,底下一樣是個完全合法(雖然醜陋)的管線表格:

1
2
3
4
5
fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09

管線表格的資料格不能包含如段落、清單之類的區塊元素,也不能包含複數行文字。

注意:Pandoc 也可以看得懂以下形式的管線表格,這是由 Emacs 的 orgtbl-mod 所繪製:

1
2
3
4
| One | Two   |
|-----+-------|
| my | table |
| is | nice |

主要的差別在於以 + 取代了部分的 |。其他的 orgtbl 功能並未支援。如果要指定非預設的直行對齊形式,你仍然需要在上面的表格中自行加入冒號。

文件標題區塊

(譯註:本節中提到的「標題」均指 Title,而非 Headers)

Extension: pandoc_title_block

如果檔案以文件標題(Title)區塊開頭

1
2
3
% title
% author(s) (separated by semicolons)
% date

這部份將不會作為一般文字處理,而會以書目資訊的方式解析。(這可用在像是單一 LaTeX 或是 HTML 輸出文件的書名上。)這個區塊僅能包含標題,或是標題與作者,或是標題、作者與日期。如果你只想包含作者卻不想包含標題,或是只有標題與日期而沒有作者,你得利用空白行:

1
2
3
4
5
6
%
% Author

% My title
%
% June 15, 2006

標題可以包含多行文字,但接續行必須以空白字元開頭,像是:

1
2
% My title
on multiple lines

如果文件有多個作者,作者也可以分列在不同行並以空白字元作開頭,或是以分號間隔,或是兩者並行。所以,下列各種寫法得到的結果都是相同的:

1
2
3
4
5
6
7
% Author One
Author Two

% Author One; Author Two

% Author One;
Author Two

日期就只能寫在一行之內。

所有這三個 metadata 欄位都可以包含標準的行內格式(斜體、連結、腳註等等)。

文件標題區塊一定會被分析處理,但只有在 --standaline (-s) 選項被設定時才會影響輸出內容。在輸出 HTML 時,文件標題會出現的地方有兩個:一個是在文件的 <head> 區塊裡--這會顯示在瀏覽器的視窗標題上--另外一個是文件的 <body> 區塊最前面。位於 <head> 裡的文件標題可以選擇性地加上前綴文字(透過 --title-prefix-T 選項)。而在 <body> 裡的文件標題會以 H1 元素呈現,並附帶 “title” 類別 (class),這樣就能藉由 CSS 來隱藏顯示或重新定義格式。如果以 -T 選項指定了標題前綴文字,卻沒有設定文件標題區塊裡的標題,那麼前綴文字本身就會被當作是 HTML 的文件標題。

而 man page 的輸出器會分析文件標題區塊的標題行,以解出標題、man page section number,以及其他頁眉 (header) 頁腳 (footer) 所需要的資訊。一般會假設標題行的第一個單字為標題,標題後也許會緊接著一個以括號包住的單一數字,代表 section number(標題與括號之間沒有空白)。在此之後的其他文字則為頁腳與頁眉文字。頁腳與頁眉文字之間是以單獨的一個管線符號 (|) 作為區隔。所以,

1
% PANDOC(1)

將會產生一份標題為 PANDOC 且 section 為 1 的 man page。

1
% PANDOC(1) Pandoc User Manuals

產生的 man page 會再加上 “Pandoc User Manuals” 在頁腳處。

1
% PANDOC(1) Pandoc User Manuals | Version 4.0

產生的 man page 會再加上 “Version 4.0” 在頁眉處。

反斜線跳脫字元

Extension: all_symbols_escapable

除了在代碼區塊或行內代碼之外,任何標點符號或空白字元前面只要加上一個反斜線,都能使其保留字面原義,而不會進行格式的轉義解讀。因此,舉例來說,下面的寫法

1
*\*hello\**

輸出後會得到

1
<em>*hello*</em>

而不是

1
<strong>hello</strong>

這條規則比原始的 markdown 規則來得好記許多,原始規則中,只有以下字元才有支援反斜線跳脫,不作進一步轉義:

1
\`*_{}[]()>#+-.!

(然而,如果使用了 markdown_strict 格式,那麼就會採用原始的 markdown 規則)

一個反斜線之後的空白字元會被解釋為不斷行的空白 (nonbreaking space)。這在 TeX 的輸出中會顯示為 ~,而在 HTML 與 XML 則是顯示為 \&#160;\&nbsp;

一個反斜線之後的換行字元(例如反斜線符號出現在一行的最尾端)則會被解釋為強制換行。這在 TeX 的輸出中會顯示為 \\,而在 HTML 裡則是 <br />。相對於原始 markdown 是以在行尾加上兩個空白字元這種「看不見」的方式進行強制換行,反斜線接換行字元會是比較好的替代方案。

反斜線跳脫字元在代碼上下文中不起任何作用。

智慧型標點符號

Extension

如果指定了 --smart 選項,pandoc 將會輸出正式印刷用的標點符號,像是將 straight quotes 轉換為 curly quotes4--- 轉為破折號 (em-dashes),-- 轉為連接號 (en-dashes),以及將 ... 轉為刪節號。不斷行空格 (Nonbreaking spaces) 將會插入某些縮寫詞之後,例如 “Mr.”。

注意:如果你的 LaTeX template 使用了 csquotes 套件,pandoc 會自動偵測並且使用 \enquote{...} 在引言文字上。

行內格式

強調

強調 某些文字,只要以 *_ 符號前後包住即可,像這樣:

1
2
This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.

重複兩個 *_ 符號以產生 更強烈的強調

1
This is **strong emphasis** and __with underscores__.

一個前後以空白字元包住,或是前面加上反斜線的 *_ 符號,都不會轉換為強調格式:

1
This is * not emphasized *, and \*neither is this\*.

Extension: intraword_underscores

因為 _ 字元有時會使用在單字或是 ID 之中,所以 pandoc 不會把被字母包住的 _ 解讀為強調標記。如果有需要特別強調單字中的一部分,就用 *

1
feas*ible*, not feas*able*.

刪除線

Extension: strikeout

要將一段文字加上水平線作為刪除效果,將該段文字前後以 ~~ 包住即可。例如,

1
This ~~is deleted text.~~

上標與下標

Extension: superscript, subscript

要輸入上標可以用 ^ 字元將要上標的文字包起來;要輸入下標可以用 ~ 字元將要下標的文字包起來。直接看範例,

1
H~2~O is a liquid.  2^10^ is 1024.

如果要上標或下標的文字中包含了空白,那麼這個空白字元之前必須加上反斜線。(這是為了避免一般使用下的 ~^ 在非預期的情況下產生出意外的上標或下標。)所以,如果你想要讓字母 P 後面跟著下標文字 ‘a cat’,那麼就要輸入 P~a\ cat~,而不是 P~a cat~

字面文字

要讓一小段文字直接以其字面形式呈現,可以用反引號將其包住:

1
What is the difference between `>>=` and `>>`?

如果字面文字中也包含了反引號,那就使用雙重反引號包住:

1
Here is a literal backtick `` ` ``.

(在起始反引號後的空白以及結束反引號前的空白都會被忽略。)

一般性的規則如下,字面文字區段是以連續的反引號字元作為開始(反引號後的空白字元為可選),一直到同樣數目的反引號字元出現才結束(反引號前的空白字元也為可選)。

要注意的是,反斜線跳脫字元(以及其他 markdown 結構)在字面文字的上下文中是沒有效果的:

1
This is a backslash followed by an asterisk: `\*`.

Extension: inline_code_attributes

圍欄代碼區塊一樣,字面文字也可以附加屬性:

1
`<$>`{.haskell}

數學

Extension: tex_math_dollars

所有介於兩個 $ 字元之間的內容將會被視為 TeX 數學公式處理。開頭的 $ 右側必須立刻接上任意文字,而結尾 $ 的左側同樣也必須緊挨著文字。這樣一來,$20,000 and $30,000 就不會被當作數學公式處理了。如果基於某些原因,有必須使用 $ 符號將其他文字括住的需求時,那麼可以在 $ 前使用反斜線跳脫字元,這樣 $ 就不會被當作數學公式的分隔符。

TeX 數學公式會在所有輸出格式中印出。至於會以什麼方式演算編排 (render) 則取決於輸出的格式:

Markdown, LaTeX, Org-Mode, ConTeXt

公式會以字面文字呈現在兩個 $ 符號之間。

reStructuredText

公式會使用 此處 所描述的 :math: 這個 “interpreted text role” 來進行演算編排。

AsciiDoc

公式會以 latexmath:[...] 演算編排。

Texinfo

公式會在 @math 指令中演算編排。

groff man

公式會以去掉 $ 後的字面文字演算編排。

MediaWiki

公式會在 <math> 標籤中演算編排。

Textile

公式會在 <span class="math"> 標籤中演算編排。

RTF, OpenDocument, ODT

如果可以的話,公式會以 unicode 字元演算編排,不然就直接使用字面字元。

Docbook

如果使用了 --mathml 旗標,公式就會在 inlineequationinformalequation 標籤中使用 mathml 演算編排。否則就會盡可能使用 unicode 字元演算編排。

Docx

公式會以 OMML 數學標記的方式演算編排。

FictionBook2

如果有使用 --webtex 選項,公式會以 Google Charts 或其他相容的網路服務演算編排為圖片,並下載嵌入於電子書中。否則就會以字面文字顯示。

HTML, Slidy, DZSlides, S5, EPUB

公式會依照以下命令列選項的設置,以不同的方法演算編排為 HTML 代碼。

  1. 預設方式是將 TeX 數學公式盡可能地以 unicode 字元演算編排,如同 RTF、DocBook 以及 OpenDocument 的輸出。公式會被放在附有屬性 class="math"span 標籤內,所以可以在需要時給予不同的樣式,使其突出於周遭的文字內容。

  2. 如果使用了 --latexmathml 選項,TeX 數學公式會被顯示於 $$$ 字元中,並放在附帶 LaTeX 類別的 <span> 標籤裡。這段內容會用 LaTeXMathML script 演算編排為數學公式。(這個方法無法適用於所有瀏覽器,但在 Firefox 中是有效的。在不支援 LaTeXMathML 的瀏覽器中,TeX 數學公式會單純的以兩個 $ 字元間的字面文字呈現。)

  3. 如果使用了 --jsmath 選項,TeX數學公式會放在 <span> 標籤(用於行內數學公式)或 <div> 標籤(用於區塊數學公式)中,並附帶類別屬性 math。這段內容會使用 jsMath script 來演算編排。

  4. 如果使用了 --mimetex 選項,mimeTeX CGI script 會被呼叫來產生每個 TeX 數學公式的圖片。這適用於所有瀏覽器。--mimetex 選項有一個可選的 URL 參數。如果沒有指定 URL,它會假設 mimeTeX CGI script 的位置在 /cgi-bin/mimetex.cig

  5. 如果使用了 --gladtex 選項,TeX 數學公式在 HTML 的輸出中會被 <eq> 標籤包住。產生的 htex 檔案之後可以透過 gladTeX 處理,這會針對每個數學公式生成圖片,並於最後生成一個包含這些圖片連結的 html 檔案。所以,整個處理流程如下:

    1
    2
    3
    pandoc -s --gladtex myfile.txt -o myfile.htex
    gladtex -d myfile-images myfile.htex
    # produces myfile.html and images in myfile-images
  6. 如果使用了 --webtex 選項,TeX 數學公式會被轉換為 <img> 標籤並連結到一個用以轉換公式為圖片的外部 script。公式將會編碼為 URL 可接受格式並且與指定的 URL 參數串接。如果沒有指定 URL,那麼將會使用 Google Chart API (http://chart.apis.google.com/chart?cht=tx&chl=)。

  7. 如果使用了 --mathjax 選項,TeX 數學公式將會被包在 \(...\)(用於行內數學公式)或 \[...\](用於區塊數學公式)之間顯示,並且放在附帶類別 math<span> 標籤之中。這段內容會使用 MathJax script 演算編排為頁面上的數學公式。

Raw HTML

Extension: raw_html

Markdown 允許你在文件中的任何地方插入原始 HTML(或 DocBook)指令(除了在字面文字上下文處,此時的 <, >& 都會按其字面意義顯示)。(技術上而言這不算擴充功能,因為原始 markdown 本身就有提供此功能,但做成擴充形式便可以在有特殊需要的時候關閉此功能。)

輸出 HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown 以及 Textile 等格式時,原始 HTML 代碼會不作修改地保留至輸出檔案中;而其他格式的輸出內容則會將原始 HTML 代碼去除掉。

Extension: markdown_in_html_blocks

原始 markdown 允許你插入 HTML「區塊」:所謂的 HTML 區塊是指,上下各由一個空白行所隔開,開始與結尾均由所在行最左側開始的一連串對稱均衡的 HTML 標籤。在這個區塊中,任何內容都會當作是 HTML 來分析,而不再視為 markdown;所以(舉例來說),* 符號就不再代表強調。

當指定格式為 markdown_strict 時,Pandoc 會以上述方式處理;但預設情況下,Pandoc 能夠以 markdown 語法解讀 HTML 區塊標籤中的內容。舉例說明,Pandoc 能夠將底下這段

1
2
3
4
5
6
<table>
<tr>
<td>*one*</td>
<td>[a link](http://google.com)</td>
</tr>
</table>

轉換為

1
2
3
4
5
6
<table>
<tr>
<td><em>one</em></td>
<td><a href="http://google.com">a link</a></td>
</tr>
</table>

Markdown.pl 則是保留該段原樣。

這個規則只有一個例外:那就是介於 <script><style> 之間的文字都不會被拿來當作 markdown 解讀。

這邊與原始 markdown 的分歧,主要是為了讓 markdown 能夠更便利地混入 HTML 區塊元素。比方說,一段 markdown 文字可以用 <div> 標籤將其前後包住來進行樣式指定,而不用擔心裡面的 markdown 不會被解譯到。

Raw TeX

Extension: raw_tex

除了 HTML 之外,pandoc 也接受文件中嵌入原始 LaTeX, TeX 以及 ConTeXt 代碼。行內 TeX 指令會被保留並不作修改地輸出至 LaTeX 與 ConTeXt 格式中。所以,舉例來說,你可以使用 LaTeX 來導入 BibTeX 的引用文獻:

1
This result was proved in \cite{jones.1967}.

請注意在 LaTeX 環境下時,像是底下

1
2
3
4
5
6
\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25 & 15 \\
26--35 & 33 \\
36--45 & 22 \\ \hline
\end{tabular}

位在 beginend 標籤之間的內容,都會被當作是原始 LaTeX 資料解讀,而不會視為 markdown。

行內 LaTeX 在輸出至 Markdown, LaTeX 及 ConTeXt 之外的格式時會被忽略掉。

LaTeX 巨集

Extension: latex_macros

當輸出格式不是 LaTeX 時,pandoc 會分析 LaTeX 的 \newcommand\renewcommand 定義,並套用其產生的巨集到所有 LaTeX 數學公式中。所以,舉例來說,下列指令對於所有的輸出格式均有作用,而非僅僅作用於 LaTeX 格式:

1
2
3
\newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$

在 LaTeX 的輸出中,\newcommand 定義會單純不作修改地保留至輸出結果。

連結

Markdown 接受以下數種指定連結的方式。

自動連結

如果你用角括號將一段 URL 或是 email 位址包起來,它會自動轉換成連結:

1
2
<http://google.com>
<sam@green.eggs.ham>

行內連結

一個行內連結包含了位在方括號中的連結文字,以及方括號後以圓括號包起來的 URL。(你可以選擇性地在 URL 後面加入連結標題,標題文字要放在引號之中。)

1
2
This is an [inline link](/url), and here's [one with
a title](http://fsf.org "click here for a good time!").

方括號與圓括號之間不能有空白。連結文字可以包含格式(例如強調),但連結標題則否。

參考連結

一個 明確 的參考連結包含兩個部分,連結本身以及連結定義,其中連結定義可以放在文件的任何地方(不論是放在連結所在處之前或之後)。

連結本身是由兩組方括號所組成,第一組方括號中為連結文字,第二組為連結標籤。(在兩個方括號間可以有空白。)連結定義則是以方括號框住的連結標籤作開頭,後面跟著一個冒號一個空白,再接著一個 URL,最後可以選擇性地(在一個空白之後)加入由引號或是圓括號包住的連結標題。

以下是一些範例:

1
2
3
4
[my label 1]: /foo/bar.html  "My title, optional"
[my label 2]: /foo
[my label 3]: http://fsf.org (The free software foundation)
[my label 4]: /bar#special 'A title in single quotes'

連結的 URL 也可以選擇性地以角括號包住:

1
[my label 5]: <http://foo.bar.baz>

連結標題可以放在第二行:

1
2
[my label 3]: http://fsf.org
"The free software foundation"

需注意連結標籤並不區分大小寫。所以下面的例子會建立合法的連結:

1
2
3
Here is [my link][FOO]

[Foo]: /bar/baz

在一個 隱性 參考連結中,第二組方括號的內容是空的,甚至可以完全地略去:

1
2
3
See [my website][], or [my website].

[my website]: http://foo.bar.baz

注意:在 Markdown.pl 以及大多數其他 markdown 實作中,參考連結的定義不能存在於嵌套結構中,例如清單項目或是區塊引言。Pandoc lifts this arbitrary seeming restriction。所以雖然下面的語法在幾乎所有其他實作中都是錯誤的,但在 pandoc 中可以正確處理:

1
2
3
> My block [quote].
>
> [quote]: /foo

內部連結

要連結到同一份文件的其他章節,可使用自動產生的 ID(參見 HTML, LaTeX 與 ConTeXt 的標題識別符 一節後半)。例如:

1
See the [Introduction](#introduction).

或是

1
2
3
See the [Introduction].

[Introduction]: #introduction

內部連結目前支援的格式有 HTML(包括 HTML slide shows 與 EPUB)、LaTeX 以及 ConTeXt。

圖片

在連結語法的前面加上一個 ! 就是圖片的語法了。連結文字將會作為圖片的替代文字(alt text):

1
2
3
4
5
![la lune](lalune.jpg "Voyage to the moon")

![movie reel]

[movie reel]: movie.gif

附上說明的圖片

Extension: implicit_figures

一個圖片若自身單獨存在一個段落中,那麼將會以附上圖片說明 (caption) 的圖表 (figure) 形式呈現。5(在 LaTeX 中,會使用圖表環境;在 HTML 中,圖片會被放在具有 figure 類別的 div 元素中,並會附上一個具有 caption 類別的 p 元素。)圖片的替代文字同時也會用來作為圖片說明。

1
![This is the caption](/url/of/image.png)

如果你只是想要個一般的行內圖片,那麼只要讓圖片不是段落裡唯一的元素即可。一個簡單的方法是在圖片後面插入一個不斷行空格:

1
![This image won't be a figure](/url/of/image.png)\

腳註

Extension: footnotes

Pandoc’s markdown 支援腳註功能,使用以下的語法:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Here is a footnote reference,1 and another.[^longnote]

腳註參考用的 ID 不得包含空白、tabs 或換行字元。這些 ID 只會用來建立腳註位置與腳註文字的對應關連;在輸出時,腳註將會依序遞增編號。 腳註本身不需要放在文件的最後面。它們可以放在文件裡的任何地方,但不能被放入區塊元素(清單、區塊引言、表格等)之中。 **Extension:** `inline_notes` Pandoc 也支援了行內腳註(儘管,與一般腳註不同,行內腳註不能包含多個段落)。其語法如下:
1
2
3
Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]

行內與一般腳註可以自由交錯使用。

引用

Extension: citations

Pandoc 能夠以數種形式自動產生引用與參考書目(使用 Andrea Rossato 的 hs-citeproc)。為了使用這項功能,你需要一個下列其中一種格式的參考書目資料庫:

Format File extension
MODS .mods
BibLaTeX .bib
BibTeX .bibtex
RIS .ris
EndNote .enl
EndNote XML .xml
ISI .wos
MEDLINE .medline
Copac .copac
JSON citeproc .json

需注意的是副檔名 .bib 一般而言同時適用於 BibTeX 與 BibLaTeX 的檔案,不過你可以使用 .bibtex 來強制指定 BibTeX。

你需要使用命令列選項 --bibliography 來指定參考書目檔案(如果有多個書目檔就得反覆指定)。

預設情況下,pandoc 會在引用文獻與參考書目中使用芝加哥「作者-日期」格式。要使用其他的格式,你需要用 --csl 選項來指定一個 CSL 1.0 格式的檔案。關於建立與修改 CSL 格式的入門可以在 http://citationstyles.org/downloads/primer.html 這邊找到。https://github.com/citation-style-language/styles 是 CSL 格式的檔案庫。也可以在 http://zotero.org/styles 以簡單的方式瀏覽。

引用資訊放在方括號中,以分號區隔。每一條引用都會有個 key,由 @ 加上資料庫中的引用 ID 組成,並且可以選擇性地包含前綴、定位以及後綴。以下是一些範例:

1
2
3
4
5
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

@ 前面的減號 (-) 將會避免作者名字在引用中出現。這可以用在已經提及作者的文章場合中:

1
Smith says blah [-@smith04].

你也可以在文字中直接插入引用資訊,方式如下:

1
2
3
@smith04 says blah.

@smith04 [p. 33] says blah.

如果引用格式檔需要產生一份引用作品的清單,這份清單會被放在文件的最後面。一般而言,你需要以一個適當的標題結束你的文件:

1
2
3
last paragraph...

# References

如此一來參考書目就會被放在這個標題後面了。

  1. 之所以有這條規則,主要是要避免以人名頭文字縮寫作為開頭的段落所帶來的混淆,像是

    1
    B. Russell was an English philosopher.

    這樣就不會被當作清單項目了。

    這條規則並不會避免以下

    1
    (C) 2007 Joe Smith

    這樣的敘述被解釋成清單項目。在這情形下,可以使用反斜線:

    1
    (C\) 2007 Joe Smith

    ↩︎

  2. David Wheeler 對於 markdown 的建議也同時影響了我。↩︎

  3. 這個方案是由 Michel Fortin 在 Markdown discussion list 的討論中所提出。↩︎

  4. 譯註:straight quotes 指的是左右兩側都長得一樣的引號,例如我們直接在鍵盤上打出來的單引號或雙引號;curly quotes 則是左右兩側不同,有從兩側向內包夾視覺效果的引號。↩︎

  5. 這項功能尚未在 RTF, OpenDocument 或 ODT 格式上實現。在這些格式中,你會得到一個在段落中只包含自己的圖片,而無圖片說明。↩︎

Please enable JavaScript to view the comments powered by Disqus. comments powered by Disqus

  1. 1.Here is the footnote.

    [^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
    belong to the previous footnote.

    { some.code }

    The whole paragraph can be indented, or just the first
    line. In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

    This paragraph won't be part of the note, because it
    isn't indented.
↩︎
坚持原创技术分享,您扫一扫将鼓励我继续写作!