抠丁客 抠丁客
项目
编辑 (2024/8/4)

开始使用 Pandoc

本文档面向不熟悉命令行工具的用户。若是命令行高手，可直接参阅用户指南或 Pandoc 的手册页。

步骤 1：安装 Pandoc

首先，根据您的平台指示安装 Pandoc。

步骤 2：打开终端窗口

Pandoc 是一个命令行工具，没有图形用户界面。因此，要使用它，您需要打开一个终端窗口：

  • 在 OS X 上，终端应用程序位于 /Applications/Utilities 中。打开 Finder，导航到应用程序，然后是实用工具。双击打开 Terminal。或者，点击屏幕右上角的聚焦搜索图标并输入 Terminal，您应在应用中看到 Terminal。

  • 在 Windows 上，您可以使用经典的命令提示符或更现代的 PowerShell 终端。若在桌面模式下使用 Windows，从开始菜单运行 cmd 或 powershell 命令。若您使用的是 Windows 8 开始屏幕，直接键入 cmd 或 powershell，然后运行 “命令提示符” 或 “Windows PowerShell” 应用。如果使用 cmd，请先输入 chcp 65001 设置编码为 UTF-8。

  • 在 Linux 上，具体操作依您的桌面环境而异：

    • 在 Unity 中，使用 Dash 的搜索功能，搜索 Terminal。或使用快捷键 Ctrl-Alt-T。
    • 在 Gnome 中，前往应用程序>附件，选择 Terminal，或用 Ctrl-Alt-T 快捷键。
    • 在 XFCE 中，进入 应用程序>系统>Terminal，或使用 Super-T 快捷键。
    • 在 KDE 中，打开 KMenu，接着 系统>终端程序 (Konsole)。

现在，您应该能看到一个带有 “提示符”（可能只是一个符号如 % ，但通常还包括用户名和目录等更多信息）的矩形框，以及一个闪烁的光标。

让我们验证 Pandoc 是否已成功安装。键入

pandoc --version

然后按回车。您应看到一条消息，显示已安装的 Pandoc 版本，并提供一些额外信息。

步骤 3：更改目录

首先，我们看看当前所在位置。在 Linux 或 OSX 上输入：

pwd

在 Windows 上则输入：

echo %cd%

然后按回车。终端会显示出您当前的工作目录。（猜猜 pwd 代表什么？）这应该是您的主目录（家目录）。

现在让我们导航到 Documents 目录下：输入

cd Documents

按回车。再输入

pwd

（Windows 上则是 echo %cd% ），再次回车。您应该处于家目录下的 Documents 子目录中。若要返回家目录，可以输入

cd ..

这里的 .. 表示 “上一级” 。

如果您还没有在 Documents 目录里，请回到那里。接下来尝试创建一个名为 pandoc-test 的子目录：

mkdir pandoc-test

现在切换到 pandoc-test 目录：

cd pandoc-test

如果提示符没有告诉您当前所在目录，可以通过再次执行

pwd

（或 Windows 上的 echo %cd% ）来确认。

好的，目前关于使用终端的知识就这些了。但这里有一个秘诀可以帮您省去大量打字：您随时可以按上箭头键回顾之前输入过的命令历史。如果您想重复使用之前的某个命令，不必重新输入，只需按上箭头键直到找到该命令即可。试试看。（您也可以使用下箭头键反向浏览。）一旦找到命令，还可以使用左右箭头键和退格/删除键进行编辑。

大多数终端还支持目录和文件名的自动补全功能。为了尝试这个功能，我们先回到 Documents 目录：

cd ..

现在输入

cd pandoc-

然后按 Tab 键而不是回车。终端会自动补全剩余部分（ test ），之后按回车。

总结一下：

  • 使用 pwd（Windows 上为 echo %cd% ）查看当前工作目录。
  • 输入 cd foo 以切换到当前工作目录下的 foo 子目录。
  • 输入 cd .. 上升到工作目录的父目录。
  • 输入 mkdir foo 在工作目录下创建名为 foo 的子目录。
  • 上箭头键回顾命令历史。
  • Tab 键补全目录和文件名。

步骤 4：使用 pandoc 作为过滤器

键入以下命令并按回车：

pandoc

你应该看到光标停留在那里，等待你输入内容。输入以下文本：

Hello *pandoc*!

- one
- two

当你完成输入（光标应位于行首时），在 OS X 或 Linux 上按下 Ctrl-D，或在 Windows 上按下 Ctrl-Z 后跟 Enter。现在，你应该看到你的文本已转换为 HTML！

<p>Hello <em>pandoc</em>!</p>
<ul>
  <li>one</li>
  <li>two</li>
</ul>

刚才发生了什么？当 pandoc 被调用而没有指定任何输入文件时，它会作为一个 “过滤器” 运行，从终端接收输入，并将其输出返回到终端。你可以利用这个特性来尝试使用 pandoc。

默认情况下，输入被解释为 pandoc 标记语言，输出为 HTML。但我们可以改变这一点。让我们尝试从 HTML 转换为 markdown：

pandoc -f html -t markdown

现在输入：

<p>Hello <em>pandoc</em>!</p>

然后按下 Ctrl-D（或在 Windows 上按下 Ctrl-Z 后跟 Enter）。你应该看到：

Hello *pandoc*!

现在尝试将某个内容从 markdown 转换为 LaTeX。你认为应该使用什么命令呢？

步骤 5：文本编辑器基础

你可能希望使用 pandoc 来转换文件，而不是从终端读取文本。这很简单，但首先我们需要在 pandoc-test 子目录中创建一个文本文件。

启动你的文本编辑器，键入以下内容：

---
title: 测试
...

# 测试！

这是对*pandoc*的测试。

- 列表一项
- 列表二项

现在将文件保存为 test1.md，存放在 Documents/pandoc-test 目录下。

注意：如果你经常使用纯文本，你可能需要一个比 记事本 或 TextEdit 更好的编辑器。你可以考虑使用 Visual Studio Code 或 Sublime Text，或者（如果你愿意花时间学习一个不熟悉的界面）Vim 或 Emacs。

步骤 6：转换文件

回到你的终端，我们应当仍处于 Documents/pandoc-test 目录下。使用 pwd 命令确认当前位置。

现在键入：

ls

（如果你在 Windows 上，则使用 dir）。这会列出当前目录中的文件。你应该能看到你创建的文件 test1.md。

要将其转换为 HTML，请使用以下命令：

pandoc test1.md -f markdown -t html -s -o test1.html

文件名 test1.md 告诉 pandoc 要转换哪个文件。选项 -s 表示创建一个带有页眉和页脚的“独立”文件，而不只是一个片段。而 -o test1.html 表示将输出放置在文件 test1.html 中。请注意，我们本可以省略 -f markdown 和 -t html，因为默认是从 markdown 转换为 HTML，但包含它们也无妨。

再次键入 ls 检查文件是否已创建。你应该能看到 test1.html。现在在浏览器中打开它。在 OS X 上，你可以键入：

open test1.html

在 Windows 上，键入：

.\test1.html

你应该能看到包含你的文档的浏览器窗口。

要创建 LaTeX 文档，只需稍微修改命令：

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

尝试在文本编辑器中打开 test1.tex。

Pandoc 经常能根据文件名扩展名推断输入和输出格式。所以，你其实可以直接使用：

pandoc test1.md -s -o test1.tex

由于 .tex 扩展名，Pandoc 知道你要创建的是 LaTeX 文档。

现在尝试创建一个 Word 文档（扩展名为 docx）。

如果你想创建 PDF，你需要安装 LaTeX。（在 OS X 上查看 MacTeX，在 Windows 上查看 MiKTeX，或在 Linux 上安装 texlive 包。）然后执行：

pandoc test1.md -s -o test1.pdf

第7步：命令行选项

至此，你已经掌握了基本知识。Pandoc提供了大量选项。现在，你可以通过阅读 Pandoc用户指南 来进一步学习它们。

下面是一个例子。使用 --mathml 选项可以让 Pandoc 将 TeX 数学公式转换成 MathML 格式。在命令行输入：

pandoc --mathml

接着输入以下文本，然后按 Ctrl-D（ 在 Windows 系统中是 Ctrl-Z 后跟 Enter ）：

$x = y^2$

现在尝试不使用 --mathml 选项重复上述操作。注意输出的差异了吗？

如果你忘记了某个选项，或者不确定支持哪些格式，可以随时运行：

pandoc --help

以获取所有支持选项的列表。

在 OS X 或 Linux 系统上，还可以通过运行：

man pandoc

来查看Pandoc的手册页。所有这些信息同样可以在用户指南中找到。

如果遇到问题，你可以在 Pandoc讨论论坛 提问。但在提问前，请确保先查阅 常见问题解答 ，并搜索论坛看看是否已经有了解答。

在本文档中