Pandoc's Markdown 語法中文翻譯

John MacFarlane, Tzeng Yuxio(translated) [速查手册] #markdown #handbook

前言

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

本文件翻譯自 Pandoc - Pandoc User’s Guide 中的 “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 風格的標題是由一行文字底下接著一行 = 符號(用於一階標題)或 - 符號(用於二階標題)所構成:

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 的規則如下:

以下是一些範例,

HeaderIdentifier
Header identifiers in HTMLheader-identifiers-in-html
Dogs?–in my house?dogs--in-my-house
[HTML], [S5], or [RTF]?html-s5-or-rtf
3. Applicationsapplications
33section

在大多數情況下,這些規則應該讓人能夠直接從標題文字推導出 ID。唯一的例外是當有多個標題具有同樣文字的情況;在這情況下,第一個標題的 ID 仍舊是透過以上規則推導而得;第二個則是在同樣 ID 後加上 -1;第三個加上 -2;以此類推。

在開啟 --toc|--table-of-contents 的選項時,這些 ID 是用來產生目錄 (Table of Contents) 所需的頁面連結。此外,這些 ID 也提供了一個簡便的方式來輸入跳到指定章節的連結。一個以 ID 產生的連結,其使用的語法看起來就像下面的例子:

    :::md
    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 假設每個標題都定義了其參考連結,因此,相較於以下的連結語法

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

你也可以單純只寫

[header identifiers]

[header identifiers][]

[the section on header identifiers][header identifiers]

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

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

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

區塊引言

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

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

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

> This is a block quote. This
paragraph has two lines.

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

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

> This is a block quote.
>
> > A block quote within a block quote.

Extension: blank_before_blockquote

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

> This is a block quote.
>> Nested.

字面(代碼)區塊

縮進代碼區塊

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

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

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

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

圍欄代碼區塊

Extension: fenced_code_blocks

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

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

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

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

~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~

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

~~~~ {#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。)反之若無支援,則上面那段代碼區塊則會以下面的形式呈現:

<pre id="mycode" class="haskell numberLines" startFrom="100">
  <code>
  ...
  </code>
</pre>

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

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

1.  one
2.  two
3.  three

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

5.  one
7.  two
1.  three

Extension: fancy_lists

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

1

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

    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 以及 reStructuredText2

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
2

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

編號範例清單

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” 之中沒有 <p> 標籤),而 markdown 則會在 “Second” 與 “Third” (但不包含 “First”)裡面置入 <p> 標籤,這是因為 “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

<!-- end of list -->

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

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

3

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

表格底下必須接著一個空白行,或是一行虛線後再一個空白行。表格標題為可選的(上面的範例中有出現)。標題需是一個以 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 下輕鬆建立。

管線表格

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

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

fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09

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

注意: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 時,文件標題會出現的地方有兩個:一個是在文件的 <head> 區塊裡--這會顯示在瀏覽器的視窗標題上--另外一個是文件的 <body> 區塊最前面。位於 <head> 裡的文件標題可以選擇性地加上前綴文字(透過 --title-prefix-T 選項)。而在 <body> 裡的文件標題會以 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\**

輸出後會得到

<em>*hello*</em>

而不是

<strong>hello</strong>

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

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

(然而,如果使用了 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{...} 在引言文字上。

4

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

行內格式

強調

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

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

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

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

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

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

Extension: intraword_underscores

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

feas*ible*, not feas*able*.

刪除線

Extension: strikeout

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

This ~~is deleted text.~~

上標與下標

Extension: superscript, subscript

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

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

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

字面文字

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

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

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

Here is a literal backtick `` ` ``.

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

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

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

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

Extension: inline_code_attributes

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

`<$>`{.haskell}

數學

Extension: tex_math_dollars

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

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

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 能夠將底下這段

<table>
	<tr>
		<td>*one*</td>
		<td>[a link](http://google.com)</td>
	</tr>
</table>

轉換為

    <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 的引用文獻:

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

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

\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 格式:

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

$\tuple{a, b, c}$

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

連結

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

自動連結

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

<http://google.com>
<[email protected]>

行內連結

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

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

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

參考連結

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

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

以下是一些範例:

[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 也可以選擇性地以角括號包住:

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

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

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

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

Here is [my link][FOO]

[Foo]: /bar/baz

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

See [my website][], or [my website].

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

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

> My block [quote].
>
> [quote]: /foo

內部連結

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

See the [Introduction](#introduction).

或是

See the [Introduction].

[Introduction]: #introduction

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

圖片

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

![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 元素。)圖片的替代文字同時也會用來作為圖片說明。

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

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

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

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

腳註

Extension: footnotes

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

Here is a footnote reference,[^1] and another.[^longnote]

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

腳註參考用的 ID 不得包含空白、tabs 或換行字元。這些 ID 只會用來建立腳註位置與腳註文字的對應關連;在輸出時,腳註將會依序遞增編號。

腳註本身不需要放在文件的最後面。它們可以放在文件裡的任何地方,但不能被放入區塊元素(清單、區塊引言、表格等)之中。

Extension: inline_notes

Pandoc 也支援了行內腳註(儘管,與一般腳註不同,行內腳註不能包含多個段落)。其語法如下:

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)。為了使用這項功能,你需要一個下列其中一種格式的參考書目資料庫:

FormatFile 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 組成,並且可以選擇性地包含前綴、定位以及後綴。以下是一些範例:

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

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

Smith says blah [-@smith04].

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

@smith04 says blah.

@smith04 [p. 33] says blah.

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

last paragraph...

# References

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


评论区🔗

你可以在这里快速开始评论,如果 name 填写为 email 时,当有回复时,会收到邮件提醒( 注:邮件提醒功能还在制作中 ).


回应区🔗

你有对这篇文章写回应吗? 你可以在这里提交你的文章网址或者推特链接(文章或推特内容需要包含这篇文章的地址,点击这里了解 Webmention):

回应内容会被 webmention.io 机器人收集,另一位机器人会在24小时内把回应展示到这里, 也欢迎通过 邮件 Twitter DM 和我讨论。

Back to top