使用 Pandoc 和 Docker 创建发布链

已发表: 2022-03-11

今天，我们将仔细研究专业人士如何获得 Pandoc 的帮助，以创建一个强大且易于实施的发布链。 Pandoc 是一个非常简单但功能强大的工具，它允许用户根据自己的要求将文档转换为各种格式。

它可以极大地简化文档和发布，甚至开辟一些新的自动化可能性。 最重要的是，Pandoc 依赖于 Git 友好的 Markdown，这意味着您还可以为您的文档实施版本控制系统，而无需任何额外的麻烦。

说到麻烦，我们将依靠 Docker 映像通过简单的拉取来安装 Pandoc 和 LaTeX。 安装软件可能很耗时，并且在开始新项目时从头开始设置工作软件环境几乎没有效率。 Docker 允许用户在几分钟内完成所有设置，无论平台如何，都有助于缓解这些问题。

此外，雇主要求您提供自己的计算机硬件的情况并不少见。 这通常被称为自带设备 (BYOD)，我们不要忘记 COVID-19 大流行使在家工作变得更加普遍。 如果没有像 Docker 这样的解决方案，就很难支持在 Windows、macOS 和 Linux 等不同硬件和操作系统上运行的应用程序。

在继续讨论 Pandoc 之前，让我们先仔细看看 Docker 容器和映像。

Docker 救援

使用 Docker 容器可以消除在新机器上安装多个软件应用程序的需要。 Docker Hub 上为大量应用程序提供了预构建的 Docker 映像。 AWS、Azure 和 Google 等领先的云提供商都提供容器注册表。 还有许多其他第三方注册表，包括 GitLab 和 Red Hat OpenShift。

大多数（如果不是全部）应用程序都可以使用图像。 这意味着不需要安装大多数应用程序及其依赖项。 该应用程序可以简单地在 Docker 容器中运行。 这方便地消除了与团队成员在不同硬件和不同操作系统上运行应用程序相关的问题。 同一个镜像可用于在任何可以运行容器的系统上运行容器，而 Docker 专家可以使这个过程变得非常快速和高效。

Pandoc 用例：文档

可能需要几种不同格式的文档。 相同的文档可能需要以不同的格式提供，例如用于演示的 HTML 和用于讲义的 PDF。 在文件格式之间进行转换可能很乏味并且需要大量时间。 一个好的解决方案是拥有一个具有单一事实来源的发布链。 所有文件都应使用相同的语言编写。 它应该是一种基于文本的语言，因为它更容易在 Git 存储库中进行版本控制和存储。

Markdown 是创建单一事实来源的不错选择。 可以将 Markdown 文档转换为各种其他格式的软件很容易获得并且往往是可靠的。

Markdown 可以很容易地转换成一系列不同的格式用于各种用途
Markdown 可以很容易地转换为一系列不同的格式以用于各种用途。

潘多克

Pandoc 是一个可以将文档转换为不同格式的软件包。 特别是它可以将 Markdown 转换为 HTML、PDF 和其他广泛使用的格式。 可以使用 Markdown 源中的模板和元数据自定义转换过程。

Pandoc 需要安装 LaTeX 才能创建 PDF 文件。 安装 Pandoc 和 LaTeX 非常耗时。 幸运的是，有一个名为pandoc/latex的 Docker 映像，它消除了安装 Docker 以外的任何东西的需要。

码头工人命令

需要找到或创建包含必要软件的合适 Docker 映像。 建议将映像拉到本地注册表，因为下载可能需要一些时间。

 docker pull pandoc/latex

要在 Docker 容器中运行命令，需要一个包装器来运行 Docker 容器并在容器中执行命令。 一个很好的解决方案是在 macOS 或 UNIX/Linux 系统上编写一个 shell 函数。 该函数可以放在任何登录脚本中，也可以放在单独的文件中，例如$HOME/.functions 。 也可以编写具有相同功能的脚本或别名。

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

此函数执行以下操作：

  • 它将命令打印到屏幕上。
  • 它从pandoc/latex映像运行 Docker 容器。
  • -it选项创建一个交互式终端会话并使命令的输出可见。
  • --rm选项在命令终止后删除容器。
  • -v $PWD:/work选项将主机上的当前目录挂载到容器中的目录/work上。
  • -w /work使容器中的/work目录成为工作目录。
  • 最后的pandoc "$@"在容器中运行pandoc命令，传递所有传递给函数的命令行选项。

shell 或脚本需要将函数加载到内存中。

 . $HOME/.functions

该函数现在本身就是一个命令，其行为方式与本地安装pandoc二进制文件的方式相同。 此方法可用于 Docker 映像中可用的任何命令。

降价到 HTML

要将 Markdown 转换为 HTML，最好在 Markdown 中使用模板和元数据。

降价到 HTML

降价元数据

Markdown 源可以有一个可以包含任意元数据的标题部分。 元数据采用键值对的形式。 这些值可以在 HTML 模板中替换。

 --- title: Document title links: prev: index next: page002 ...

标题以仅包含三个破折号的行开头--- 。 它以仅包含三个点...的行结束。 键是单个单词，后跟一个冒号及其值。 键可以嵌套。 该示例显示了名为title, links.prev和links.next的键的定义。

这种方法对每个页面使用单独的文件。 在示例中，上一页是index.md ，当前页是page001.md ，下一页是page002.md 。 在实践中，将使用更有意义的文件名，以便更容易重新排序和插入页面。

HTML 模板

HTML 模板只是一个 HTML 文件。 可以在美元符号之间添加元数据替换和简单的控制结构。 这是 Pandoc 的 HTML 模板的简单示例：

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

该示例显示了一个模板。 $body$被转换为 HTML 的 Markdown 文本替换。 只有在 Markdown 标头中定义了元数据时，条件语句才会生成 HTML 链接。

从 Markdown 生成 HTML

Pandoc 只需要被告知输入和输出文件的名称以及任何模板文件。 默认输入文件格式是Markdown 。 它可以从指定的输出文件扩展名推断输出文件格式。

生成输出的命令可以是脚本或 makefile。

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

对于Project目录中的每个.md文件，如果输出文件早于输入文件或不存在，它将在HTML/Project目录中创建相应的.html文件。

从 Markdown 生成 Beamer PDF

Beamer 是一个用于制作演示文稿的 LaTeX 包。 输出为 PDF 幻灯片。

从 Markdown 生成 Beamer PDF

相同的 Markdown 源文件可用于生成 beamer PDF。

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

命令详情如下：

  • -t beamer选项表示使用 LaTeX 和 beamer 生成 PDF。
  • -o选项指定输出文件。
  • -V选项选择投影仪主题和颜色主题。
  • 该命令以 Markdown 文件列表结尾，这些文件将按给定顺序连接。

所有处理都在 Docker 容器内执行。

降价到 PDF

将 Markdown 文档转换为 PDF 文档也很简单。 PDF 总是通过首先将 Markdown 转换为 LaTeX 来生成的。 可以将元数据添加到 Markdown 标头以自定义输出，例如设置纸张大小和边距大小。

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

从 Markdown 生成 PDF

将 Markdown 转换为 PDF 的命令很简单：

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

-s 选项创建一个独立的文档。

结论

不再需要花费很多天来安装软件。 只需在 Docker 容器中运行命令即可消除安装需求。 许多应用程序在 Docker Hub 上都有合适的 Docker 镜像。 如果软件需要更新，只需拉取最新的 Docker 镜像。

设置一台新计算机只需安装 Docker、拉取必要的映像并创建一些脚本。

不再需要创建不同格式的文档。 Markdown 等单一格式可用于所有文档。 然后像 Pandoc 这样的工具可以从 Markdown 生成大量不同格式的文档。

由于 Markdown 是一个文本文件，当签入 Git 存储库时，可以使用完整的版本历史记录。 Git 存储库还自动呈现 Markdown 并允许人们对更改发表评论，而无需在文档文件本身中使用凌乱的更改历史记录。