写在前面

如今许多 Markdown 编辑器都标配了多格式导出功能，其底层核心往往离不开 Pandoc 的支持。长久以来，我对 Pandoc 仅停留在概念层面的了解。直到近期阅读了一篇深度分享，作者讲述了如何通过 Pandoc 与 Org 模式构建「单一格式笔记库」，从而彻底摆脱排版与格式的束缚，这让我对其背后的工作流产生了浓厚兴趣。

采用单一纯文本格式（如 ：Markdown）的核心优势，不仅在于创作时能屏蔽排版干扰、专注内容本身，更在于其极低的数据解析门槛。纯文本天然具备极佳的机器可读性，这意味着在 AI 时代，AI Agent 可以无缝接入并处理这些笔记。

这正是纯文本笔记面向未来的核心竞争力。云端笔记的智能化受限于平台生态，封闭或复杂的混合格式则存在巨大的数据转换摩擦；而纯文本（Markdown, Org, YAML, LaTeX 甚至 JSON）则完全规避了这些痛点，是真正的 AI-Ready 资产。

在这样的工作流中，Pandoc 扮演了不可或缺的「桥梁」角色。它补齐了纯文本生态的最后一块短板，打破了单一格式与复杂应用场景（如出版、分发、打印、网页渲染等）之间的转换壁垒，让内容创作与最终呈现形成清晰的「工具链」分工。

原作者：Joe Riad； 原文地址：

https://medium.com/gitconnected/i-only-make-documents-in-one-format-8b50bd61972d

火箭君翻译，并略做编辑。

正文

我一直讨厌和同学/同事一起处理共享文档。总会有人因为使用的 Word 版本略有不同，或者干脆用了另一套办公软件，结果在自己的电脑上出问题。我们也可以共享 PDF，但不容易编辑。

假设我们对共同的文档格式达成了一致，那那些期望我把网页发布到共享服务器上的人怎么办？我是否必须把 Word 文档的信息重复一遍以 HTML 格式呈现？虽然有导出服务，但还是很麻烦。

简而言之，在对文档有不同假设和不同使用场景的人之间共享文档，很容易变成一场噩梦。这就是为什么当我发现有一个可以为我处理所有这些工作的自由软件工具时，我感到震惊。更重要的是，它让我只需撰写一次文档，就能根据需要将其发布为多种不同的格式。

我要介绍的是 Pandoc 。它几乎可以在你能想到的任意两种文档格式之间进行转换。

将内容与格式分离

在我谈论 Pandoc 之前，我想介绍一下我不久前接触到的文档设计概念。这种思路影响了我在 Pandoc 中制作文档的方法。

这个想法很简单：文档的内容应该与其格式相互独立。在处理文档时，应当先填写内容，之后再考虑格式。如果我们只编辑过 Office Word 文档，这个概念可能会让人感到很陌生。

在 Word（或 LibreOffice Writer 或类似软件）中编辑文档时，通常在输入内容的同时编辑格式。我们会关注字体大小、颜色、哪些内容加粗、哪些不加粗、标题如何格式化等……如果更有经验一些，可以使用文本样式。例如，可以指定所有标题应为加粗、14 磅并使用某种字体，而普通文本应为 12 磅并使用另一种字体。

这样在创作内容时我们就不必纠结于格式的细枝末节了。这是将格式与内容分离的第一步。Word 仍然可能具有干扰性，因为你在输入时就能看到最终文档的大致样子，所以你会更容易对格式问题敏感并产生分心。

我第一次真正接触到这个概念是在大学开始用 LaTeX 写学术论文的时候。在 LaTeX 中，我们在输入时看不到最终文档的样子（不过，也可以参见 LyX）。

我们只需指定内容和结构元素（例如：这是一级标题、这是列表中的一项等……），LaTeX 引擎会将你的指令编译成最终文档。它使用预定义的样式完成排版，能以很小的成本让文档看起来相当专业。

当然问题是，与不太懂 LaTeX 的人协作处理 LaTeX 文档相当困难。最终文档是 DVI 或 PDF 格式，也不容易编辑。

有一段时间，我只能在个人写作中采用这种文档设计方式。任何需要与他人分享的东西都必须是 Word 文档，用惯了 LaTeX 之后，Word 这种方式让我感到相当沮丧。

我的理想情况是用一种标记语言（比如 Markdown）来指定文档的内容和结构，然后让一个引擎将其格式化为我所需的文档类型。 Pandoc 正是提供了这一点，这也是我第一次接触它时，会觉得它带来了一种范式转变的原因。。

关于 Pandoc

Pandoc 几乎可以在我听过的任何两种文档格式之间进行转换。我认为，如果格式不是 Pandoc 能处理的那些之一，那么它大概非常小众，用户自己应该已经是这种格式的专家了，并且能够把它转换为其他格式。

为了高效实现这一点， Pandoc 将任何文档格式转换为一个通用的内部表示（中间码），然后再把该内部表示翻译为目标格式。这样，与其为每一对可能的格式编写转换器，不如只需为每种格式实现与内部表示之间的翻译器。

这种能力的妙处在于，它允许你用一种格式来撰写文档，并根据需要使用相同的源文档发布为多种不同的格式。关键是选择一种表达力足够强的格式。当我刚开始使用 Pandoc 时，我认为 Markdown 非常适合这个目的。
下面是一个包含不同结构和格式元素的 Markdown 文档的小示例：

要将此文件（假设名为 mydoc.md ）转换为 docx 格式，我可以在命令行中这样做：

pandoc -f markdown -t docx -o output_file_name.docx mydoc.md

其中 -f 指定 源格式， -t 指定 目标格式。

下面是该文档在我的 LibreOffice Writer 中的渲染效果：

由于 Markdown 允许我指定标题级别， Pandoc 会识别文档结构并在 docx 文件中使用标题样式进行复现。因此一级标题使用「Heading 1」样式，二级标题使用「Heading 2」样式。这意味着，例如，如果我想要的话，可以很容易地生成目录。

但乐趣并未止步于此。我可以使用相同的 Markdown 源文档来创建一个 HTML 文档：

pandoc -f markdown -t html -o mydoc.html mydoc.md

得到如下结果：

当然，这只是普通的 HTML。通过指定一个 CSS 文件可以让它变得更好。下面是一个示例 CSS 文件。如果我将其保存为 pandoc.css 并以这种方式转换我的文件：

pandoc f markdown -t html -o mydoc.html mydoc.md 
--css=pandoc.css --standalone

同理，我也可以将相同的文档转换为 PDF，或其它格式。

即使像方程式这样的专业支持也非常棒。如果转换为 HTML，我们可以使用 MathJax 让它们以类 LaTeX 的质量渲染。如果转换为 PDF，它们会通过 LaTeX 渲染；如果转换为 docx、odt、pptx 等格式，它们则会被转换为本地的、可编辑的方程式。我们在 Markdown 中输入方程时，仍然使用 LaTeX 语法。

也可以通过 YAML 向文档添加元数据：

可以通过过滤器进一步扩展功能，你甚至可以使用 Lua 为自己的文档格式编写自定义转换器（关于这点，请参见 Pandoc 网站）。

长期以来，这一直为我带来极大帮助，但我总觉得 Markdown 在表达能力上相当有限。这就引出了我今天实际使用的文档格式。

Org 与 Pandoc 导出

当我遇到 Markdown 的局限时，我也刚开始接触 Emacs。Emacs 里有一个名为 Org 的模式，它本身就是一套效率很高的生产力工具。在其众多功能中，它有一种用于指定文档结构的标记语言。

当我调出 Org 导出对话框时，看到的是：

类型非常丰富，我很难想到我可能需要使用却找不到的格式。当然，如果找不到，Org 也允许我编写自定义导出器。

大家可能会认为我在从 Markdown 切换到 Org 时遇到了问题。因为我已经有很多用 Markdown 写的笔记和文档，需要花时间将它们转换为 Org。

事实证明这根本不是问题： Pandoc 当然可以将 Markdown 转换为 Org！

有时，我希望 Pandoc 的功能比现有的稍微强大一些。这时我发现了过滤器。基本上可以拦截 Pandoc 所理解的文档内部结构，并在导出前对其进行修改。

Pandoc 过滤器

正如此处详细解释的， Pandoc 首先将文档转换为它可以以 JSON 格式输出的抽象语法树（AST）。筛选机制允许你编写自己的代码来拦截此 JSON，对其进行修改，然后输出供 Pandoc 完成将其转换为目标格式的剩余工作。

Pandoc 的创建者创建了 pandocfilters Python 包以便于这一过程（https://pypi.org/project/pandocfilters/）。

大家也可以使用过滤器来预处理引文和参考文献（这就是我最初的用例），将实时获取的数据（例如股票行情）注入到文档中，或使用几乎任何只要 Python 能做到的方式来转换文档。

我自己的例子

以下是以 Org 为核心采用这种创作流程后，我获得的一些具体收益：

我用 Org 写完了整篇博士论文，并通过 LaTeX 导出成 PDF。这是一个巨大的工程，涉及自定义 LaTeX 样式文件和参考文献样式等……最棒的是，我不用处理 LaTeX 的样板内容就能发布高质量的 LaTeX 文档。到了准备答辩幻灯片的时候，我使用了 LaTeX Beamer。我能够毫无阻碍地将论文 Org 文件中的内容直接复制到演示文稿的 Org 文件中。

我把在工作中学到的所有东西（从修复常见 IT 问题到新的技术知识）都记在 Org 里。我能把部分笔记以 HTML 的形式发布，供队友参考，也把一些笔记以 docx 格式发布，为我的主管生成任务报告。这让我看起来像是愿意多下功夫制作高质量文档的人。当然，我不需要为实现这一点而操心 HTML 或 docx 的细节。

在手机上访问我的 Org 笔记并不容易，所以（有趣的是）我用 Pandoc 将它们全部转换成 Markdown，以便在 Joplin 中用更友好的方式浏览它们。

最后

为了避免在我必须为不同场景创建并与同事共享的各种文档格式之间频繁切换，我决定大多数文档都用 Org 撰写，然后导出为所需的任何格式。为此我使用 Org 的导出引擎或 Pandoc 。

我喜欢这种方法的原因是它完全免费且完全以纯文本形式存在。我可以将文档放入版本控制、检索它们、对其中一些处理流程做自动化处理等…… 然后再发布一些真正精美的文档与他人共享。

如果大家也需要产出大量文档，我强烈建议和我一样尝试使用单一文本格式 Org， 或者 Org+Pandoc 两者兼用。