安装 Pandoc

获取最新 pandoc 发布版本最简单的方法是使用安装程序。

下载最新安装程序

对于安装 pandoc 的其他替代方法，请参见下面针对您操作系统的标题部分。

Windows

Pandoc 的 下载页面 提供了一个程序包安装器。此安装器将会安装 pandoc，替换旧版本，并更新您的路径以包含 pandoc 二进制文件所在的目录。

如果您不愿意使用 msi 安装程序，我们也提供一个包含 pandoc 二进制文件和文档的 zip 文件。只需解压这个文件并将二进制文件移动到您选择的目录即可。

另外，您也可以使用 Chocolatey 来安装 pandoc：

choco install pandoc

Chocolatey 同样能安装其他与 Pandoc 集成的软件。例如，要安装 rsvg-convert（来自 librsvg，用于补充不支持 SVG 的格式）、Python（以便使用 Pandoc 过滤器）和 MiKTeX（用于通过 LaTeX 排版 PDF）：

choco install rsvg-convert python miktex

或者，您可以使用 winget 安装 pandoc：

winget install --source winget --exact --id JohnMacFarlane.Pandoc

使用多种安装方法可能导致 pandoc 有两个独立的安装实例；在切换至另一种安装方法前，建议先正确卸载 pandoc。

默认情况下，Pandoc 通过 LaTeX 创建 PDF。我们推荐通过 MiKTeX 来安装它。但是，通过使用 --pdf-engine 选项，您可以指定其他程序来完成这一任务。

macOS

Pandoc 的 下载页面 提供了一个程序安装包。如果您之后想卸载该程序包，可以通过下载此脚本并使用 perl 运行它来实现：perl uninstall-pandoc.pl。

或者，您可以使用 Homebrew 安装 pandoc：

brew install pandoc

Homebrew 也能安装其他与 Pandoc 协同工作的软件。例如，为了安装 librsvg（其 rsvg-convert 工具可处理不支持 SVG 的格式）、Python（用于应用 Pandoc 过滤器）以及 BasicTeX（用于通过 LaTeX 排版 PDF），可以执行：

brew install librsvg python homebrew/cask/basictex

注意

在不受支持的 macOS 版本（超过三个主要版本）上，Homebrew 会从源代码进行安装，这将需要更多时间和磁盘空间来编译 ghc 编译器及其依赖的 Haskell 库。

我们还提供了一个包含二进制文件和手册页的 zip 文件，供不愿使用安装器的用户选择。只需解压文件并将二进制文件及手册页移动到您喜欢的任意目录即可。

默认情况下，Pandoc 通过 LaTeX 创建 PDF。鉴于完整 MacTeX 安装会占用约 4GB 的磁盘空间，我们推荐使用 BasicTeX 或 TinyTeX，并在需要时使用 tlmgr 工具安装额外的包。如果您遇到提示缺少字体的错误：

tlmgr install collection-fontsrecommended

然而，通过使用 --pdf-engine 选项，您可以为该任务指定其他程序。

Linux

检查您的包管理器中的 pandoc 版本是否过时。Pandoc 已被纳入 Debian、Ubuntu、Slackware、Arch、Fedora、NixOS、openSUSE、gentoo 和 Void 等发行版的仓库中。

为了获取最新版本，我们在下载页面提供了针对 amd64 架构的二进制包。

该可执行文件是静态链接的，没有动态依赖项或对外部数据文件的依赖。注意：由于静态链接，此包中的 pandoc 二进制文件无法使用需要外部 C 语言编写的 lua 模块的 lua 过滤器。

我们同时提供了 tarball 和 deb 安装包。要安装 deb 包，使用以下命令：

sudo dpkg -i $DEB

其中 $DEB 是下载的 deb 文件的路径。这将安装 pandoc 可执行文件和 man 手册页。

如果您使用基于 RPM 的发行版，可能可以使用 alien 从我们的下载页面安装 deb 包。

在任何发行版上，您都可以通过以下命令从 tarball 安装到 $DEST（例如，/usr/local/ 或 $HOME/.local ）：

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

其中 $TGZ 是下载的压缩 tarball 的路径。对于 2.0 版本之前的 Pandoc（未提供 tarball），可以尝试使用：

ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST

您也可以按照下面 “从源代码编译” 部分的指示从源代码安装。请注意，大多数发行版的包仓库中都有 Haskell 平台。例如，在 Debian/Ubuntu 上，可以通过 apt-get install haskell-platform 来安装。

默认情况下，Pandoc 通过 LaTeX 创建 PDF。我们建议通过包管理器安装 TeX Live。（在 Debian/Ubuntu 上，使用 apt-get install texlive 。）然而，通过使用 --pdf-engine 选项，您可以为此任务指定其他程序。

Chrome OS

在 Chrome 操作系统上，可以使用 chromebrew 包管理器通过以下命令安装 pandoc：

crew install pandoc

这将自动为正在使用的特定设备构建和配置 pandoc。

BSD

Pandoc 已被纳入 NetBSD、FreeBSD 和 OpenBSD 的 ports 仓库中。

Docker

官方的 Pandoc Docker 镜像可以在 https://github.com/pandoc/dockerfiles 和 Docker Hub 上找到。

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

Pandoc 可以通过 GitHub Actions 来运行。想查看一些实例，可以参考：https://github.com/pandoc/pandoc-action-example.

GitLab CI/CD

Pandoc 可以通过 GitLab CI/CD 来运行。想查看一些实例，可以参考：https://gitlab.com/pandoc/pandoc-ci-example.

从源代码编译

如果因为某些原因，没有适用于您的平台的二进制包，或者您想要对 pandoc 进行修改开发，或使用未发布的版本，您可以选择从源代码进行安装。

获取 pandoc 源代码

源代码 tarball 可以在找到。例如，要获取 1.17.0.3 版本的源代码，可以使用以下命令：

wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz
tar xvzf pandoc-1.17.0.3.tar.gz
cd pandoc-1.17.0.3

或者，您可以通过克隆仓库来获取开发代码：

git clone https://github.com/jgm/pandoc.git
cd pandoc

注意：有时开发中的代码可能会出现问题，或者依赖于需要单独安装的其他库。除非您确实清楚自己在做什么，否则请安装最新发布的版本。

快速 Stack 方法

从源代码构建 Pandoc 最简单的方式是使用 Stack:

1. 安装 Stack。注意，Pandoc 要求 Stack 版本 >= 1.7.0。

   stack setup
   

   如果您没有 GHC 编译器，stack setup 会自动下载它。接着，

   stack install pandoc-cli
   

   stack install 会将 Pandoc 可执行文件安装到 ~/.local/bin 目录下，您应将此目录添加到 PATH 环境变量中。这个过程会花费一些时间，并会占用相当大的磁盘空间。

快速 Cabal 方法

1. 安装 ghcup。这将为您提供 GHC 和 Cabal。

2. 更新您的包数据库：

   cabal update
   

3. 使用 Cabal 安装 Pandoc 及其依赖项：

   cabal install pandoc-cli
   

   此过程将安装从 HackageDB 自动下载的 Pandoc 发布版本。在 Linux/Unix/macOS 上，Pandoc 可执行文件将被放置在 $HOME/.cabal/bin 目录下；在 Windows 上，则位于 %APPDATA%\cabal\bin。确保此目录已添加到您的系统路径中。

4. 如果您想安装修改过的或开发版本的 Pandoc，先切换到源代码目录，然后再运行上述命令——Cabal 将使用 cabal.project 中提及的所有项目的本地代码。

现在，您应该能够运行 Pandoc：

pandoc --help

5. Cabal 不会安装 pandoc.1 手册页，但您可以从源代码的 man/ 目录中将其复制到 /usr/local/share/man/man1/ 或您系统中存放手册页的相应位置。

自定义 Cabal 安装方法

这是一个分步过程，可为构建和安装提供最大控制。大多数用户应使用快速安装，但此信息可能对打包者有用。更多细节，请参阅 Cabal 用户指南。这些指示假设 Pandoc 源代码目录是您的工作目录。您将需要版本 2.0 或更高的 cabal。

1. 安装依赖项：

   除了 Haskell 平台之外，您还需要许多额外的库。您可以使用以下命令安装它们全部：

   cabal update
   cabal install --only-dependencies
   

2. 配置：

   cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
   --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
   --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
   --mandir=DIR --flags=FLAGSPEC --enable-tests
   

   所有选项都有合理的默认值，可根据需要覆盖。

   FLAGSPEC是一个 Cabal 配置标志列表，可以选挿以 - 开头（强制标志为 false），并以空格分隔。Pandoc 的标志包括：

   • embed_data_files：将所有数据文件嵌入二进制文件中（默认不嵌入）。这对于创建可重定位的二进制文件很有帮助。
   • pandoc-cli的标志包括：
   • lua：编译支持 Lua 过滤器和自定义编写器。
   • server：当可执行文件重命名（或作为符号链接）为pandoc-server时，编译支持 HTTP 服务器模式运行。

3. 构建：

   cabal build
   cabal test
   

4. 构建 API 文档：

   cabal haddock --html-location=URL --hyperlink-source
   

创建可重定位的二进制文件：

可以编译 Pandoc，使其使用的数据文件嵌入到二进制文件中。生成的二进制文件可以从任何目录运行，完全自成一体。使用 cabal 时，在 cabal configure 或 cabal install 命令中添加 -fembed_data_files 。

使用 stack 时，使用 --flag pandoc:embed_data_files 。

运行测试：

Pandoc 附带了一个自动化测试套件。使用 cabal 运行测试：cabal test；使用 stack 运行测试：stack test。

要运行特定测试（按名称模式匹配），使用 -p 选项：

cabal test --test-options='-p markdown'

或使用 stack：

stack test --test-arguments='-p markdown'

通常，向测试参数中添加 -j4（并行运行测试）和 --hide-successes（不以成功结果杂乱输出）也很有帮助。

如果您向 Pandoc 添加新功能，请同时添加测试，遵循现有测试的模式。测试套件代码位于 test/test-pandoc.hs 。如果您添加新的读取器或写入器，最简单的方法可能是向测试目录添加一些数据文件，并修改 test/Tests/Old.hs 。否则，最好修改与您更改的 Pandoc 模块对应的 test/Tests 层次结构下的模块。

运行基准测试：

构建并运行基准测试：

cabal configure --enable-benchmarks && cabal build
cabal bench

或使用 stack：

stack bench

快速运行基准测试：

为了更快地运行基准测试，使用较小的样本量：

cabal bench --benchmark-options='-s 20'

只运行 Markdown 基准测试：

cabal bench --benchmark-options='markdown'