Pandoc的安装与使用

Pandoc，号称文本格式转换的瑞士军刀, 可以在各种标记文档格式之间转换

下面符号意义如下:

  • ↔︎ 可以导入为此格式，也可以从此格式导出
  • ← 可以从此格式导出
  • → 可以导入为此格式

Pandoc支持的文档格式

各种轻量标记语言

  • ↔︎ Markdown (including CommonMark and GitHub-flavored Markdown)
  • ↔︎ reStructuredText
  • ↔︎ AsciiDoc
  • ↔︎ Emacs Org-Mode
  • ↔︎ Emacs Muse
  • ↔︎ Textile
  • ↔︎ txt2tags

HTML 格式

  • ↔︎ (X)HTML 4
  • ↔︎ HTML5

Word格式

  • ↔︎ Microsoft Word docx 可以从word文档导入导出
  • ↔︎ OpenOffice/LibreOffice ODT 可以从OpenOffice ODT文档导入导出
  • → OpenDocument XML
  • → Microsoft PowerPoint 可以导出为微软PPT

PDF

  • → 通过 pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, prince, context, 或者 pdfroff支持导出为pdf文档

CSV

← CSV tables 可以从CSV表格导入

其他各种格式

  • ↔︎ EPUB version 2 or 3
  • ↔︎ FictionBook2
  • → GNU TexInfo
  • ↔︎ Haddock markup
  • ↔︎ roff man
  • → roff ms
  • ↔︎ LaTeX
  • → ConTeXt
  • ↔︎ DocBook version 4 or 5
  • ↔︎ JATS
  • → TEI Simple
  • ↔︎ OPML
  • ↔︎ BibTeX
  • ↔︎ BibLaTeX
  • ↔︎ CSL JSON
  • ↔︎ CSL YAML
  • ↔︎ Jupyter notebook (ipynb)
  • → InDesign ICML
  • → LaTeX Beamer
  • → Slidy
  • → reveal.js
  • → Slideous
  • → S5
  • → DZSlides
  • ↔︎ MediaWiki markup
  • ↔︎ DokuWiki markup
  • ← TikiWiki markup
  • ← TWiki markup
  • ← Vimwiki markup
  • → XWiki markup
  • → ZimWiki markup
  • ↔︎ Jira wiki markup
  • → custom writers can be written in lua.

可见Pandoc支持日常使用的的markdown、html、pdf、word文档等的导入导出操作。

Pandoc支持的文档特性

Pandoc支持很多有用的markdown标记格式扩展, 包括文档元数据(title、author、date)、脚注、表格、定义列表、上标和下标、strikeout删除线、增强的有序列表(开始数字和数字样式很重要)、running example lists(运行举例列表)、格式加亮的定界代码块、智能引用、破折号、椭圆符号?、HTML块中的markdown、内联的Latex. 如果需要markdown严格兼容模式、上面这些扩展可以关闭.

可以在markdown文档中使用Latex数学(甚至包括marcors宏命令)。 pandoc提供了几种在HTML内显示数学公式符号的不同的方法, 包括MathJax和MathML的翻译。 LaTeX数学会被转换(根据输出格式需要)为unicode,原生的word公式对象，MathML或者roff方程式。

安装Pandoc安装

通过安装包安装

选择适合自己操作系统的可安装包,下载到本地安装即可, 有的系统可能需要将pandoc命令所在目录添加到系统环境变量PATH中 下载最新版本

Windows系统

在下载页面download page有现成的安装包msi installer, 下载后运行安装包会安装pandoc, 同时替换(可能存在的)旧版本, 更新系统路径环境变量以包含pandoc的二进制命令所在目录。

如果不喜欢msi installer安装包, 下载页面页提供了Zip文件包含pandoc的二进制命令文件和文档. 下载也很容易，解压缩文件并将二进制命令文件移动到您选择的目录中(如果需要随处调用, 需要将二进制文件所在目录添加到windows路径环境变量中)。

另外，可以通过Chocolatey安装pandoc:

choco install pandoc

Chocolatey也可以安装与pandoc整合的其他软件,比如rsvg-convert (来自librsvg, svg支持库), Python (使用Pandoc滤镜)以及 MiKTeX (使用LaTeX设置PDF文档格式):

choco install rsvg-convert python miktex

默认情况下, Pandoc使用Latex来创建PDF文档, 我们建议通过MiKTeX安装Latex.

macOS

在下载页面download page有安装包.如果以后想卸载pandoc,可以下载这个卸载脚本, 在终端运行 perl uninstall-pandoc.pl 卸载pandoc.

另外, 您可以使用Homebrew安装pandoc:

brew install pandoc

Homebrew也可以用来安装与pandoc整合的其他软件,比如rsvg-convert (来自librsvg, svg支持库), Python (使用Pandoc滤镜)以及 BasicTeX (使用LaTeX设置PDF文档格式):

brew install librsvg python homebrew/cask/basictex

不喜欢安装包的话, 下载页面也提供了包含二进制文件和manpage文档的Zip文件 下载也很容易，解压缩文件并将二进制命令文件移动到您选择的目录中(如果需要随处调用, 需要将二进制文件所在目录添加到环境变量中).

缺省情况下, Pandoc创建PDf需要使用Latex. 由于完整的 MacTeX安装需要大约4G磁盘空间, 因此建议使用BasicTeX 或者 TinyTeX, 并使用tlmgr工具按需安装额外的包裹.如果遇到提示字体缺失错误提示:

tlmgr install collection-fontsrecommended

Linux

Pandoc在Debian, Ubuntu, Slackware, Arch, Fedora, NiXOS, openSUSE, gentoo and Void的资源库中有资源包.

在**download page**界面有amd64架构的最新的二进制版本. 这里的二进制版本可执行文件是静态链接的， 没有动态依赖外部数据文件。 由于是静态链接, 无法使用需要使用C语言编写的的lua模块的lua过滤器。

提供了tarball和deb安装包, 安装deb包:

sudo dpkg -i $DEB

这里 $DEB 是下载的deb包的磁盘路径. 这会安装pandoc 可执行文件和man page文档.

If you use an RPM-based distro, you may be able to install the deb from our download page using alien. 如果使用基于RPM的发行版, 可以使用alien命令安装下载页面的deb包，

对每个发行安装包, 可以通过如下命令安装到目标路径$DEST (比如, /usr/local/ 或者 $HOME/.local):

tar xvzf $TGZ –strip-components 1 -C $DEST

这里 $TGZ 是下载的tarball的zip文件路径.

对于PDF输出, 需要Latex. 我们建议通过包管理器安装TeX Live (在Debian/Ubuntu系统上命令是 apt-get install texlive.)

Chrome OS

Chrome OS中, 使用chromebrew 包管理器安装:

1

crew install pandoc

BSD

NetBSD 和 FreeBSD ports 资源库中有pandoc安装包

Docker

官方的Docker pandoc映像位于https://github.com/pandoc/dockerfiles和 dockerhub

pandoc/core 中包含 pandoc.

pandoc/latex中包含使用pandoc生成pdf文档需要的 最小化的latex安装文件.

在Docker中运行pandoc,将 README.md 转化为 README.pdf命令如下:

docker run –rm –volume “pwd:/data” –user id -u:id -g pandoc/latex README.md -o README.pdf

GitHub Actions

可以在GitHub Actions中运行pandoc. 例子请参考 https://github.com/pandoc/pandoc-action-example

从源代码编译

请参考pandoc官网文档

验证安装

安装完毕后，在终端console输入下面命令

pandoc --version

会看到类似下面的输出(下面是macos的输出，不同系统输出有差别)

1
2
3
4
5
6
7
8

pandoc 1.19.2.1
Compiled with pandoc-types 1.17.0.4, texmath 0.9, skylighting 0.1.1.4
Default user data directory: /Users/guanyc/.pandoc
Copyright (C) 2006-2016 John MacFarlane
Web:  http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

下面的例子使用macos

例子1: 命令行里转换markdown为html

打开终端console, 输入pandoc,然后输入简单markdown文档

1
2
3
4
5
6

guanycdeMacBook-Pro:~ guanyc$ pandoc
#标题1
##标题2
###标题3
this is a 段落

输入完毕, 换行,然后同时按键CTRL+d, 会看到markdown转化成的html输出

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

guanycdeMacBook-Pro:~ guanyc$ pandoc
#标题1
##标题2
###标题3
this is a 段落                       
<h1 id="标题1">标题1</h1>
<h2 id="标题2">标题2</h2>
<h3 id="标题3">标题3</h3>
<p>this is a 段落</p>
guanycdeMacBook-Pro:~ guanyc$

例子2: 命令行里转换markdown转换为latex

命令如下

1
2
3
4
5

guanycdeMacBook-Pro:~ guanyc$ pandoc -f markdown -t latex
#标题1
##标题2
###标题3
this is a 段落

然后换行, 同时按键CTRL+d，命令结束，输出应该类似下面这样:

1
2
3
4
5
6
7

\section{标题1}\label{ux6807ux98981}

\subsection{标题2}\label{ux6807ux98982}

\subsubsection{标题3}\label{ux6807ux98983}

this is a 段落

例子3: 转换mardkown文件为html

首先编写一个简单的markdown文件

1
2
3
4
5
6

# This is a test document

Here is some text in the document.

- This is 列表第一行
- With 这是第二行

假设markdown文件为input.md 使用下面命令生成名为output.html的html文件

1

pandoc -o output.html input.md

输出文件output.html应该类似这样:

1
2
3
4
5
6

<h1 id="this-is-a-test-document">This is a test document</h1>
<p>Here is some text in the document.</p>
<ul>
<li>This is 列表第一行</li>
<li>With 这是第二行</li>
</ul>

应用稍微复杂一点的命令,

1

pandoc input.md -f markdown -t html -s -o output.html

参数 -f markdown 表示从markdown转换 参数 -t html 表示转换成html 参数 -s 表示要不仅仅生成html片段，还包含页面页脚等格式. 现在的ouput.html，应该类似这样

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <title></title>
  <style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<h1 id="this-is-a-test-document">This is a test document</h1>
<p>Here is some text in the document.</p>
<ul>
<li>This is 列表第一行</li>
<li>With 这是第二行</li>
</ul>
</body>
</html>

例子4: pandoc转换mardkown文件生成pdf(使用中文字体,LaTeX中文模板等)

继续使用例子3中的markdown文件, input.md 尝试生成pdf文档

1

pandoc input.md -s -o test2.pdf

出错 我的系统提示没安装pdflatex

1

pandoc: pdflatex not found. pdflatex is needed for pdf output.

按照上面macos安装部分,需要安装BasicTeX (使用LaTeX设置PDF文档格式)

brew install librsvg python homebrew/cask/basictex

安装完毕, 继续生成pdf

1

pandoc input.md -s -o test2.pdf

命令失败, 输出如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

! Package inputenc Error: Unicode character 列 (U+5217)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.67   This is 列

Try running pandoc with --latex-engine=xelatex.

应该是xelatex才能处理中文，试试加上命令参数–latex-engine=xelatex

1

pandoc input.md -s -o test2.pdf --latex-engine=xelatex

命令运行顺利!

打开pdf文档看看，中文无显示？丢失?

网上查询下,应该是要添加字体和latex的中文模板才行, 参考神器Pandoc的安装与使用

这里 -V mainfont=STSong 使用了支持中文的字体

下载使用pandoc latex 样例模板

1

pandoc input.md -s -o test2.pdf --latex-engine=xelatex --template=default.latex -V mainfont=STSong

这个可以生成pdf, 但是如果中文行太长还是会截断, 应该是latex模板的问题(TODO 实在搞不懂, 以后再找/自己编写?合适模板)

另外(见下面例子)可以生成docx word文档，然后word文档另存为pdf，或许是懒人懒办法吧

例子4: pandoc转换mardkown文件生成word docx

再编写一个简单的markdown文件 中文长一点

1
2
3
4
5
6

# This is a test document

Here is some text in the document.

- This is 列表第一行
- 这是第二行，很长很长的中文在转换的word文档中是能够能得到合适的展现呢，我们很期望啊。你呢，这段文字就非常长啊, 做个测试吧

保存为long-input.md

将long-input.md markdown文件导出为word docx文件

1
2

pandoc long-input.md -f markdown -t docx -s -o output.docx

得到的docx word文件打开如图:

中文处理问题不大，这样可以从word导出为pdf，不会发生内容截断.

例子5: pandoc转换mardkown文件生成html 带CSS

适用于markdown生成的html的css一枚,下载保存为buttondown.CSS

1

pandoc long-input.md -s -c buttondown.css -o outputwithcsslink.html

生成加载外部css的html文件

如果需要内嵌CSS，像下面这样

例子5: pandoc转换mardkown文件生成html 内嵌CSS

参考[buttondown]

1

pandoc long-input.md -s -c buttondown.css  --self-contained -o outputwithinlinecss.html

buttondown.css中文本内嵌在outputwithinlinecss.html内

更多

更多内容，请参考 pandoc user guide

参考资料