Pandoc是用于将文件从一种标记语言转换为另一种标记语言的命令行工具。 标记语言使用标签来注释文档的各个部分。 常用的标记语言包括Markdown，ReStructuredText，HTML，LaTex，ePub和Microsoft Word DOCX。
用简单的英语， Pandoc允许您将一堆文件从一种标记语言转换成另一种标记语言。 典型示例包括将Markdown文件转换为演示文稿，LaTeX，PDF甚至是ePub。
本文将说明如何使用Pandoc从一种标记语言（在本例中为Markdown）以多种格式生成文档。 它将指导您完成Pandoc的安装，显示如何创建几种类型的文档，并提供有关如何编写易于移植到其他格式的文档的提示。 它还将说明使用元信息文件在文档的内容和元信息（例如作者姓名，使用的模板，书目样式等）之间创建分隔的价值。
安装及要求
在大多数Linux发行版中默认安装Pandoc。 本教程使用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$
$\Box\diamond p\equiv\diamond p$
$\int_{0}^{1} x dx = \left[ \frac{1}{2}x^2 \right]_{0}^{1} = \frac{1}{2}$
$e^x = \sum_{n=0}^\infty \frac{x^n}{n!} = \lim_{n\rightarrow\infty} (1+x/n)^n$
通过输入以下命令将LaTeX文档转换为名为mathMathML.html的网站：
pandoc math.tex -s --mathml -o mathMathML.html
标志-s告诉Pandoc生成一个独立的网站（而不是一个片段，因此它将包含head和body HTML标签），并且–mathml标志强制Pandoc将LaTeX中的数学转换为MathML，可以通过现代浏览器。
查看网站结果和代码 ; 代码存储库包含一个Makefile，使事情变得更加简单。
制作Reveal.js幻灯片
使用Pandoc从Markdown文件生成简单的演示很容易。 幻灯片包含顶层幻灯片和下面的嵌套幻灯片。 可以通过键盘控制演示文稿，您可以从一个顶层幻灯片跳到下一个顶层幻灯片，也可以按每个顶层显示嵌套的幻灯片。 这种结构在基于HTML的表示框架中很典型。
让我们创建一个名为SLIDES的幻灯片文档（请参阅代码存储库 ）。 首先，添加以％符号开头的幻灯片的元信息（例如，标题，作者和日期）：
% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017
例如，如果我们要创建一个标题为“ 案例研究”的演示文稿，并以名为“ 葡萄酒管理系统 ”的顶层幻灯片开头，请编写：
% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017
# Wine Management System
要将内容（例如解释新管理系统及其实现的幻灯片）放在此顶层部分中，请使用Markdown标头H2。 让我们再添加两张幻灯片（下面的第7和14行，Markdown中的标题2 ，由##指定）：
- 第二张第一张幻灯片的标题为“ 创意”，并显示了瑞士国旗的图像
- 第二个第二级幻灯片的标题为“ 实施”。
% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017
# Wine Management System
## <img src="img/SwissFlag.png" style="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" style="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 manifest.js指定我们将要输出一个Discover.js演示文稿
- -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
\begin{table}[h]
\begin{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模板中可用的元信息，请输入：
pandoc -D FORMAT
例如，LaTeX的模板为：
pandoc -D latex
根据以下内容输出内容：
$if(title)$
\title{$title$$if(thanks)$\thanks{$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)$
\titlegraphic{\includegraphics{$titlegraphic$}}
$endif$
$if(logo)$
\logo{\includegraphics{$logo$}}
$endif$
$endif$
\begin{document}
如您所见，有title ， thank ， author ， subtitle和Institute模板变量（还有许多其他变量可用）。 这些可以使用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文档转换为其他格式方面做得非常好。
7505
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
