編譯自： https://opensource.com/article/18/9/intro-pandoc

作者： Kiko Fernandez-reyes

譯者： jlztan

這篇指南介紹如何使用 Pandoc 將文檔轉換為多種不同的格式。

Pandoc 是一個命令行工具，用於將文件從一種標記語言轉換為另一種標記語言。標記語言使用標籤來標記文檔的各個部分。常用的標記語言包括 Markdown、ReStructuredText、HTML、LaTex、ePub 和 Microsoft Word DOCX。

簡單來說， Pandoc 允許你將一些文件從一種標記語言轉換為另一種標記語言。典型的例子包括將 Markdown 文件轉換為演示文稿、LaTeX，PDF 甚至是 ePub。

本文將解釋如何使用 Pandoc 從單一標記語言（在本文中為 Markdown）生成多種格式的文檔，引導你完成從 Pandoc 安裝，到展示如何創建多種類型的文檔，再到提供有關如何編寫易於移植到其他格式的文檔的提示。

文中還將解釋使用元信息文件對文檔內容和元信息（例如，作者姓名、使用的模板、書目樣式等）進行分離的意義。

Pandoc 安裝和要求

Pandoc 默認安裝在大多數 Linux 發行版中。本教程使用 pandoc-2.2.3.2 和 pandoc-citeproc-0.14.3。如果不打算生成 PDF，那麼這兩個包就足夠了。但是，我建議也安裝 texlive，這樣就可以選擇生成 PDF 了。

通過以下命令在 Linux 上安裝這些程序：

sudo apt-get install pandoc pandoc-citeproc texlive

您可以在 Pandoc 的網站上找到其他平台的 安裝說明 。

我強烈建議安裝 pandoc-crossref ，這是一個「用於對圖表，方程式，表格和交叉引用進行編號的過濾器」。最簡單的安裝方式是下載 預構建的可執行文件 ，但也可以通過以下命令從 Haskell 的軟體包管理器 cabal 安裝它：

cabal update

cabal install pandoc-crossref

如果需要額外的 Haskell 安裝信息 ，請參考 pandoc-crossref 的 GitHub 倉庫。

幾個例子

我將通過解釋如何生成三種類型的文檔來演示 Pandoc 的工作原理：

• 由包含數學公式的 LaTeX 文件創建的網頁
• 由 Markdown 文件生成的 Reveal.js 幻燈片
• 混合 Markdown 和 LaTeX 的合同文件

創建一個包含數學公式的網站

Pandoc 的優勢之一是以不同的輸出文件格式顯示數學公式。例如，我們可以從包含一些數學符號（用 LaTeX 編寫）的 LaTeX 文檔（名為 math.tex）生成一個網頁。

math.tex 文檔如下所示：

% Pandoc math demos

$a^2 + b^2 = c^2$

$v(t) = v_0 + frac{1}{2}at^2$

$gamma = frac{1}{sqrt{1 - v^2/c^2}}$

$exists x forall y (Rxy equiv Ryx)$

$p wedge q models p$

$Boxdiamond pequivdiamond p$

$int_{0}^{1} x dx = left[ frac{1}{2}x^2
ight]_{0}^{1} = frac{1}{2}$

$e^x = sum_{n=0}^infty frac{x^n}{n!} = lim_{n
ightarrowinfty} (1+x/n)^n$

通過輸入以下命令將 LaTeX 文檔轉換為名為 mathMathML.html 的網站：

pandoc math.tex -s --mathml -o mathMathML.html

參數 -s 告訴 Pandoc 生成一個獨立的網頁（而不是網頁片段，因此它將包括 HTML 中的 head 和 body 標籤），-mathml 參數強制 Pandoc 將 LaTeX 中的數學公式轉換成 MathML，從而可以由現代瀏覽器進行渲染。

看一下 網頁效果 和 代碼 ，代碼倉庫中的 Makefile 使得運行更加簡單。

製作一個 Reveal.js 幻燈片

使用 Pandoc 從 Markdown 文件生成簡單的演示文稿很容易。幻燈片包含頂級幻燈片和下面的嵌套幻燈片。可以通過鍵盤控制演示文稿，從一個頂級幻燈片跳轉到下一個頂級幻燈片，或者顯示頂級幻燈片下面的嵌套幻燈片。 這種結構在基於 HTML 的演示文稿框架中很常見。

創建一個名為 SLIDES 的幻燈片文檔（參見 代碼倉庫 ）。首先，在 ％ 後面添加幻燈片的元信息（例如，標題、作者和日期）：

% Case Study

% Kiko Fernandez Reyes

% Sept 27, 2017

這些元信息同時也創建了第一張幻燈片。要添加更多幻燈片，使用 Markdown 的一級標題（在下面例子中的第5行，參考 Markdown 的一級標題 ）生成頂級幻燈片。

例如，可以通過以下命令創建一個標題為 「Case Study」、頂級幻燈片名為 「Wine Management System」 的演示文稿：

% Case Study

% Kiko Fernandez Reyes

% Sept 27, 2017

# Wine Management System

使用 Markdown 的二級標題將內容（比如包含一個新管理系統的說明和實現的幻燈片）放入剛剛創建的頂級幻燈片。下面添加另外兩張幻燈片（在下面例子中的第 7 行和 14 行 ，參考 Markdown 的二級標題 ）。

• 第一個二級幻燈片的標題為 「Idea」，並顯示瑞士國旗的圖像
• 第二個二級幻燈片的標題為 「Implementation」

% Case Study

% Kiko Fernandez Reyes

% Sept 27, 2017

# Wine Management System

## <img src="img/SwissFlag.png" stylex="vertical-align:middle"/> Idea

## Implementation

我們現在有一個頂級幻燈片（＃Wine Management System），其中包含兩張幻燈片（## Idea 和 ## Implementation）。

通過創建一個由符號 > 開頭的 Markdown 列表，在這兩張幻燈片中添加一些內容。在上面代碼的基礎上，在第一張幻燈片中添加兩個項目（第 9-10 行），第二張幻燈片中添加五個項目（第 16-20 行）：

% Case Study

% Kiko Fernandez Reyes

% Sept 27, 2017

# Wine Management System

## <img src="img/SwissFlag.png" stylex="vertical-align:middle"/> Idea

>- Swiss love their **wine** and cheese

>- Create a *simple* wine tracker system


## Implementation

>- Bottles have a RFID tag

>- RFID reader (emits and read signal)

>- **Raspberry Pi**

>- **Server (online shop)**

>- Mobile app

上面的代碼添加了馬特洪峰的圖像，也可以使用純 Markdown 語法或添加 HTML 標籤來改進幻燈片。

要生成幻燈片，Pandoc 需要引用 Reveal.js 庫，因此它必須與 SLIDES 文件位於同一文件夾中。生成幻燈片的命令如下所示：

pandoc -t revealjs -s --self-contained SLIDES

-V theme=white -V slideNumber=true -o index.html

上面的 Pandoc 命令使用了以下參數：

• -t revealjs 表示將輸出一個 revealjs 演示文稿
• -s 告訴 Pandoc 生成一個獨立的文檔
• --self-contained 生成沒有外部依賴關係的 HTML 文件
• -V 設置以下變數：
• theme=white 將幻燈片的主題設為白色
• slideNumber=true 顯示幻燈片編號
• -o index.html 在名為 index.html 的文件中生成幻燈片

為了簡化操作並避免鍵入如此長的命令，創建以下 Makefile：

all: generate

generate:

pandoc -t revealjs -s --self-contained SLIDES

-V theme=white -V slideNumber=true -o index.html

clean: index.html

rm index.html

.PHONY: all clean generate

可以在 這個倉庫 中找到所有代碼。

製作一份多種格式的合同

假設你正在準備一份文件，並且（這樣的情況現在很常見）有些人想用 Microsoft Word 格式，其他人使用自由軟體，想要 ODT 格式，而另外一些人則需要 PDF。你不必使用 OpenOffice 或 LibreOffice 來生成 DOCX 或 PDF 格式的文件，可以用 Markdown 創建一份文檔（如果需要高級格式，可以使用一些 LaTeX 語法），並生成任何這些文件類型。

和以前一樣，首先聲明文檔的元信息（標題、作者和日期）：

% Contract Agreement for Software X

% Kiko Fernandez-Reyes

% August 28th, 2018

然後在 Markdown 中編寫文檔（如果需要高級格式，則添加 LaTeX）。例如，創建一個固定間隔的表格（在 LaTeX 中用 hspace{3cm} 聲明）以及客戶端和承包商應填寫的行（在 LaTeX 中用 hrulefill 聲明）。之後，添加一個用 Markdown 編寫的表格。

創建的文檔如下所示：

創建此文檔的代碼如下：

% Contract Agreement for Software X

% Kiko Fernandez-Reyes

% August 28th, 2018

...

### Work Order

egin{table}[h]

egin{tabular}{ccc}

The Contractor & hspace{3cm} & The Customer \

& & \

& & \

hrulefill & hspace{3cm} & hrulefill \

%

Name & hspace{3cm} & Name \

& & \

& & \

hrulefill & hspace{3cm} & hrulefill \

...

end{tabular}

end{table}

vspace{1cm}

+--------------------------------------------|----------|-------------+

| Type of Service | Cost | Total |

+:===========================================+=========:+:===========:+

| Game Engine | 70.0 | 70.0 |

| | | |

+--------------------------------------------|----------|-------------+

| | | |

+--------------------------------------------|----------|-------------+

| Extra: Comply with defined API functions | 10.0 | 10.0 |

| and expected returned format | | |

+--------------------------------------------|----------|-------------+

| | | |

+--------------------------------------------|----------|-------------+

| **Total Cost** | | **80.0** |

+--------------------------------------------|----------|-------------+

要生成此文檔所需的三種不同輸出格式，編寫如下的 Makefile：

DOCS=contract-agreement.md

all: $(DOCS)

pandoc -s $(DOCS) -o $(DOCS:md=pdf)

pandoc -s $(DOCS) -o $(DOCS:md=docx)

pandoc -s $(DOCS) -o $(DOCS:md=odt)

clean:

rm *.pdf *.docx *.odt

.PHONY: all clean

4 到 7 行是生成三種不同輸出格式的具體命令：

如果有多個 Markdown 文件並想將它們合併到一個文檔中，需要按照希望它們出現的順序編寫命令。例如，在撰寫本文時，我創建了三個文檔：一個介紹文檔、三個示例和一些高級用法。以下命令告訴 Pandoc 按指定的順序將這些文件合併在一起，並生成一個名為 document.pdf 的 PDF 文件。

pandoc -s introduction.md examples.md advanced-uses.md -o document.pdf

模板和元信息

編寫複雜的文檔並非易事，你需要遵循一系列獨立於內容的規則，例如使用特定的模板、編寫摘要、嵌入特定字體，甚至可能要聲明關鍵字。所有這些都與內容無關：簡單地說，它就是元信息。

Pandoc 使用模板生成不同的輸出格式。例如，有一個 LaTeX 的模板，還有一個 ePub 的模板，等等。這些模板的元信息中有未賦值的變數。使用以下命令找出 Pandoc 模板中可用的元信息：

pandoc -D FORMAT

例如，LaTex 的模版是：

pandoc -D latex

按照以下格式輸出：

$if(title)$

itle{$title$$if(thanks)$ hanks{$thanks$}$endif$}

$endif$

$if(subtitle)$

providecommand{subtitle}[1]{}

subtitle{$subtitle$}

$endif$

$if(author)$

author{$for(author)$$author$$sep$ and $endfor$}

$endif$

$if(institute)$

providecommand{institute}[1]{}

institute{$for(institute)$$institute$$sep$ and $endfor$}

$endif$

date{$date$}

$if(beamer)$

$if(titlegraphic)$

itlegraphic{includegraphics{$titlegraphic$}}

$endif$

$if(logo)$

logo{includegraphics{$logo$}}

$endif$

$endif$

egin{document}

如你所見，輸出的內容中有標題、致謝、作者、副標題和機構模板變數（還有許多其他可用的變數）。可以使用 YAML 元區塊輕鬆設置這些內容。 在下面例子的第 1-5 行中，我們聲明了一個 YAML 元區塊並設置了一些變數（使用上面合同協議的例子）：

---

title: Contract Agreement for Software X

author: Kiko Fernandez-Reyes

date: August 28th, 2018

---

(continue writing document as in the previous example)

這樣做非常奏效，相當於以前的代碼：

% Contract Agreement for Software X

% Kiko Fernandez-Reyes

% August 28th, 2018

然而，這樣做將元信息與內容聯繫起來，也即 Pandoc 將始終使用此信息以新格式輸出文件。如果你將要生成多種文件格式，最好要小心一點。例如，如果你需要以 ePub 和 HTML 的格式生成合同，並且 ePub 和 HTML 需要不同的樣式規則，該怎麼辦？

考慮一下這些情況：

• 如果你只是嘗試嵌入 YAML 變數 css:style-epub.css，那麼將從 HTML 版本中移除該變數。這不起作用。
• 複製文檔顯然也不是一個好的解決方案，因為一個版本的更改不會與另一個版本同步。
• 你也可以像下面這樣將變數添加到 Pandoc 命令中：

pandoc -s -V css=style-epub.css document.md document.epub

pandoc -s -V css=style-html.css document.md document.html

我的觀點是，這樣做很容易從命令行忽略這些變數，特別是當你需要設置數十個變數時（這可能出現在編寫複雜文檔的情況中）。現在，如果將它們放在同一文件中（meta.yaml 文件），則只需更新或創建新的元信息文件即可生成所需的輸出格式。然後你會編寫這樣的命令：

pandoc -s meta-pub.yaml document.md document.epub

pandoc -s meta-html.yaml document.md document.html

這是一個更簡潔的版本，你可以從單個文件更新所有元信息，而無需更新文檔的內容。

結語

通過以上的基本示例，我展示了 Pandoc 在將 Markdown 文檔轉換為其他格式方面是多麼出色。

via: https://opensource.com/article/18/9/intro-pandoc

作者： Kiko Fernandez-Reyes 選題： lujun9972 譯者： jlztan 校對： wxy

本文由 LCTT 原創編譯， Linux中國 榮譽推出

點擊「了解更多」可訪問文內鏈接

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！