转换文本和文档即代码格式

如果你有pandoc支持的任何文件格式的文档，转换格式会非常简单。

当您将 pandoc 用作简单文档即代码系统的平台时，它的真正威力会变得更加清晰。 docs-as-code 的前提是应用一些软件开发技术和原则，并在编写文档时使用它们，特别是对于计算机程序开发项目。您可以应用它来开发任何类型的文档。

安装 pandoc

要在 Ubuntu 上安装 pandoc，请使用以下命令：

sudo apt-get install pandoc

在 Fedora 上，使用命令：

sudo dnf install pandoc

在 Manjaro 上，使用命令：

sudo pacman-Syu pandoc

您可以使用--version 选项检查您安装的版本：

pandoc--version

使用没有文件的 pandoc

如果您使用没有任何命令行选项的 pandoc，它也会接受输入的文本。只需按 Ctrl + D 即可让计算机知道您已完成输入。 pandoc 想让你输入 Markdown 格式，它会以 HTML 格式输出。

看下面的例子：

pandoc

输入一些 Markdown 行并按 Ctrl + D。

导入后，pandoc 立即生成等效的 HTML 输出。

但是，为了使用 pandoc 有用，我们确实需要使用文件。

基本降价

Markdown 是一种轻量级的标记语言，适用于某些字符。您可以使用简单的文本编辑器来创建 Markdown 文件。

Markdown 可以很容易地阅读，因为没有视觉混乱来分散对文本的注意力。 Markdown 文档中的格式与其所代表的格式相同。以下是一些基本内容：

1. 要斜体，请将文本放在星号中。
2. 对于粗体，请使用两个星号。
3. 标题用数字符号/# 符号表示。文本与函数# 之间用空格分隔。对顶级标题使用一个函数 #，对二级标题使用两个函数，等等。
4. 要创建项目符号列表，请以星号开始列表的每一行，并在文本前插入一个空格。
5. 要创建编号列表，请以数字开头，后跟一个句点，然后在文本前插入一个空格。
6. 要创建超链接，请将站点名称放在方括号 ([]) 中，将 URL 放在方括号 [()] 中。
7. 要插入图像，请在方括号 (! []) 前输入一个感叹号。在括号中输入图片的任何替代文本。然后，将图像的路径放在方括号 [() 示例] 中。

转换文件

文件转换非常简单。 pandoc 通常可以找到您使用的文件格式。例如，这里将从 Markdown 创建一个 HTML 文件。-o 选项（输出）告诉 pandoc 我们要创建的文件的名称：

pandoc-o sample.html sample.md

示例 Markdown 文件 sample.md 包含 Markdown 的一小部分，如下图所示。

一个名为 sample.html 的文件被创建。当您双击该文件时，默认浏览器将打开它。

现在，创建一个可以在 LibreOffice Writer 中打开的 Open Document Format：

pandoc-o sample.odt sample.md

ODT 文件的内容与 HTML 文件相同。

指定文件格式

-f (from) 和-t (to) 选项用于告诉 pandoc 您要转换的文件格式。如果您使用与其他相关格式共享文件扩展名的文件格式，这会很有帮助。例如，TeX 和 LaTeX 都使用“.tex”扩展名。

-s（独立）选项也用于 pandoc 来创建所有必要的 LaTeX 预览，使文档成为完整、封闭且格式良好的 LaTeX 文档。如果没有-s（独立）选项，输出仍然是 LaTeX，它可以包含在另一个 LaTeX 文档中，但它会解析为独立的 LaTeX 文档。

输入以下命令：

pandoc-f markdown-t latex-s-o sample.tex sample.md

如果您在文本编辑器中打开 sample.tex 示例文件，您应该会看到已创建的 LaTeX。如果您有 LaTeX 编辑器，请打开 TEX 文件以查看如何解释 LaTeX 排版命令的预览。最小化窗口以适应下图使屏幕看起来局促，但实际上它仍然可以正常工作。

这是一个名为 Texmaker 的 LaTeX 编辑器。如果要安装，请在 Ubuntu 中键入以下命令：

sudo apt-get install texmaker

在 Fedora 上，输入以下命令：

sudo dnf install texmaker

在 Manjaro 上，使用命令：

sudo pacman-Syu texmaker

使用模板转换文件

使用模板，您可以指定在创建文档时使用哪个 pandoc。例如，要求 pandoc 使用带有--css 选项的层叠样式表 (CSS) 中定义的样式。

下面创建了一个包含文本的小 CSS 文件。它更改标题级别的顶部和底部间距。它还将文本颜色更改为白色，将背景颜色更改为蓝色：

h1 { 颜色：#FFFFFF;背景色：#3C33FF；边距顶部：0px；底边距：1px； }

完整命令在这里：

pandoc-o sample.html-s--css sample.css sample.md

另一个在处理 HTML 文件时可用的调整选项包括 Markdown 文件中的 HTML 标记。它将作为标准 HTML 标记转换为新创建的 HTML 文件。

这种技术应该只在输出 HTML 时使用。如果您使用多种文件格式，pandoc 将忽略非 HTML 文件的 HTML 标记，并将其转换为文本格式。

我们还可以指定在创建 ODT 文件时使用哪种类型。打开一个白色的 LibreOffice Writer 页面并调整标题样式和字体以满足您的需要。下面的示例添加了一个标题和一个书签。之后，将您的文档另存为“odt-template.odt”。

我们现在可以使用--reference-doc 选项将此模板用作模板：

pandoc-o sample.odt--reference-doc=odt-template.odt sample.md

将此与之前的 ODT 示例进行比较。此文档使用不同的字体，具有彩色标题和页码。但是，它是从 Markdown 文件的同一个“sample.md”文件创建的。

参考模板可用于指示文档制作的不同阶段。

创建 PDF 文件

默认情况下，pandoc 使用 LaTeX PDF 工具来创建 PDF 文件。最简单的方法是安装 LaTeX 编辑器，例如 Texmaker。

由于Tex 和LaTeX 都比较大，如果你的硬盘不够用或者你从来不使用TeX 或LaTeX，创建一个ODT 文件。然后您只需在 LibreOffice Writer 中打开它并将其另存为 PDF。

文档即代码

使用 Markdown 编程语言的一些好处：

1. 在简单的文本文件中快速工作。许多编辑器，包括 gedit、Vim 和 Emacs，都对 Markdown 文本使用高亮显示。
2. 您将拥有所有文档版本的时间表。如果您将文档存储在 VCS（例如 Git）中，您可以轻松查看同一文件的两个版本之间的差异。但是，这仅在文件为纯文本时才有效，因为这就是 VCS 的工作方式。
3. VCS 可以记录时间以及进行任何更改的人员。这是特别用如果您经常在大型项目的团队中工作，则非常有用。 它还为文档提供了一个中央存储库。 有很多云 Git 存储服务，例如 GitHub、GitLab 和 BitBucket，都有免费和付费版本。
4. 您可以创建多种格式的文档。 只需几个简单的 shell 脚本，您就可以从 CSS 和引用中获取模板。 如果您将文档存储在与 CI/CD 平台集成的 VCS 存储库中，则可以在开发软件时自动创建这些文档。