请帮助乌克兰！
赞助商
Pandoc   一个通用文档转换器

安装 Pandoc

获取最新版 Pandoc 最简单的方法是使用安装程序。

下载最新安装程序

有关安装 Pandoc 的其他方法，请参阅下方适用于您的操作系统的标题。

注意：我们提供的（或 Conda Forge 上可用的）静态链接 Pandoc 二进制文件存在限制。它们无法使用依赖于用 C 编写的 Lua 模块的 Lua 过滤器。如果您需要这些过滤器提供的功能，请考虑其他安装方法。

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

或者，您可以使用 Conda forge 安装 Pandoc。

使用多种安装方法可能导致 Pandoc 的两个独立安装；建议在切换到其他安装方法之前，正确卸载 Pandoc。

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

macOS

Pandoc 的下载页面上提供了软件包安装程序。如果您以后想卸载该软件包，可以通过下载此脚本并使用 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 库的额外时间和磁盘空间。

您也可以使用 MacPorts 安装 Pandoc

port install pandoc

或者，您可以使用 Conda forge 安装 Pandoc。

我们也提供了一个包含二进制文件和手册页的 zip 文件，供那些不喜欢使用安装程序的用户。只需解压文件，并将二进制文件和手册页移动到您喜欢的任何目录即可。

默认情况下，Pandoc 使用 LaTeX 创建 PDF。由于完整的 MacTeX 安装会占用四千兆字节的磁盘空间，我们建议使用 BasicTeX 或 TinyTeX，并使用 tlmgr 工具根据需要安装额外的软件包。如果您收到字体未找到的错误警告

tlmgr install collection-fontsrecommended

但是，您可以使用选项 --pdf-engine 为此任务指定其他程序。

Linux

检查您的包管理器中的 Pandoc 版本是否不是过时的。Pandoc 位于 Debian、Ubuntu、Slackware、Arch、Fedora、NixOS、openSUSE、gentoo 和 Void 软件仓库中。

要获取最新版本，我们在下载页面提供了适用于 amd64 架构的二进制软件包。

该可执行文件是静态链接的，没有动态依赖项或对外部数据文件的依赖项。

提供了 tarball 和 deb 安装程序。要安装 deb

sudo dpkg -i $DEB

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

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

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

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

其中 $TGZ 是已下载的压缩 tarball 文件的路径。对于不提供 tarball 的 Pandoc 2.0 之前版本，请尝试

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

或者，您可以使用 Conda forge 安装 Pandoc。

您还可以从源代码安装，使用下方 从源代码编译 部分的说明。请注意，大多数发行版在其包存储库中都有 Haskell 平台。例如，在 Debian/Ubuntu 上，您可以使用 apt-get install haskell-platform 进行安装。

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

Chrome OS

在 Chrome OS 上，可以使用 chromebrew 包管理器通过以下命令安装 Pandoc

crew install pandoc

这将自动为您使用的特定设备构建和配置 Pandoc。

BSD

Pandoc 位于 NetBSD、FreeBSD 和 OpenBSD 端口 存储库中。

Conda Forge

您可以使用 Conda Forge 工具安装 Pandoc，例如 Conda、[Micro]Mamba 或 Pixi。Conda Forge 还包含多个 LaTeX 和其他与 Pandoc 相关的软件包（包括 pandoc-citeproc、pandoc-plot、通过 librsvg 的 rsvg-convert 等）。注意： Conda Forge 安装的是静态链接的可执行文件。

conda install -c conda-forge pandoc
pixi global install pandoc
micromamba install pandoc

Docker

Pandoc 的官方 Docker 镜像可以在 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

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 可以在 https://hackage.haskell.org/package/pandoc 找到。例如，获取 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
cd pandoc

注意：有时开发代码可能损坏或依赖于必须单独安装的其他库。除非您非常清楚自己在做什么，否则请安装最新发布的版本。

快速 Stack 方法

从源代码构建 Pandoc 最简单的方法是使用 stack

  1. 安装 stack。请注意，Pandoc 需要 stack >= 1.7.0。

  2.   stack setup
  stack install pandoc-cli

    如果您没有 ghc 编译器，stack setup 将自动下载。stack install 会将 pandoc 可执行文件安装到 ~/.local/bin，您应该将其添加到您的 PATH 环境变量中。这个过程将耗费一些时间，并占用相当大的磁盘空间。

快速 Cabal 方法

  1. 安装 ghcup。这将为您提供 ghc 和 cabal。

  2. 更新您的软件包数据库

    cabal update

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

    cabal install pandoc-cli

    此过程将安装已发布的 Pandoc 版本，该版本将自动从 HackageDB 下载。pandoc 可执行文件在 Linux/Unix/macOS 上将放置在 $HOME/.cabal/bin 中，在 Windows 上将放置在 %APPDATA%\cabal\bin 中。请确保此目录在您的路径中。

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

  4. 您现在应该能够运行 pandoc 了

    pandoc --help

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

自定义 Cabal 方法

这是一个分步过程，可最大程度地控制构建和安装。大多数用户应使用快速安装，但此信息可能对打包人员有用。有关更多详细信息，请参阅 Cabal 用户指南。这些说明假定 Pandoc 源代码目录是您的工作目录。您将需要 Cabal 2.0 或更高版本。

  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，将 -fembed_data_files 添加到 cabal configure 或 cabal install 命令中。

使用 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 目录中，并修改 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'