Pandoc转换深度解析：哪些内容能在标记语言转换中幸存

标记语言转换的"损耗"问题为何值得关注

随着 Pandoc 3.10.2 版本的发布，这款"文档转换界的瑞士军刀"再次引发技术社区的热议。无论是将 Markdown 转换为 HTML，还是反向操作，甚至将各类纯文本文件转换为 PDF，Pandoc 几乎都能胜任。但一个长期被低估的核心问题浮出水面：在不同标记语言之间转换时，究竟有多少内容能够"幸存"，又有多少会在转换过程中悄然丢失？

这绝非一个无关紧要的技术细节。对于需要跨平台、跨格式管理文档的团队和个人而言，转换损耗直接影响内容的可维护性与长期价值。本文将深入剖析 Pandoc 的转换机制，探讨现代标记语言的设计哲学，并解释 AST（抽象语法树）为何正在成为决定转换质量的关键因素。

Pandoc 的核心机制：以 AST 为中心的转换架构

为什么 AST 是 Pandoc 转换的灵魂

Pandoc 之所以能在数十种标记格式之间自由转换，秘诀在于它并非简单地做"文本替换"，而是将输入文档解析为一个统一的抽象语法树（AST）。这个中间表示层剥离了具体语法的外壳，只保留文档的结构与语义——标题、段落、列表、强调、链接、表格等核心元素。

抽象语法树是编译器理论中的核心概念，最早广泛应用于编程语言的编译与解释过程中。AST 将源代码或文档的语法结构以树形数据结构表示，其中每个节点代表一个语法构造（如表达式、语句、段落或标题），而"抽象"意味着它省略了具体的语法细节（如 Markdown 中的 # 号或 HTML 中的 <h1> 标签），只保留语义上有意义的信息。在文档转换领域，AST 的引入意味着将文档从"字符串操作"提升为"结构化操作"——类似于数据库查询比直接操作文本文件更可靠。Pandoc 的 AST 使用 Haskell 的代数数据类型定义，其核心类型包括 Block（块级元素如段落、标题、代码块）和 Inline（行内元素如加粗、链接、脚注），这种严格的类型系统确保了转换过程中的类型安全。

Pandoc 使用 Haskell 语言编写，这一选择并非偶然。Haskell 是一种纯函数式编程语言，其强大的类型系统和模式匹配能力使其天然适合处理语法树的构建与变换。Haskell 的代数数据类型（Algebraic Data Types）允许开发者以声明式方式精确定义 AST 的所有可能节点类型，编译器会在编译时检查所有模式匹配是否穷尽，从而从源头避免了"遗漏某种文档元素"这类错误。这种类型安全特性在文档转换场景中至关重要——当 Pandoc 新增一种块级或行内元素时，所有 Writer（输出模块）都必须显式处理该新元素，否则代码无法通过编译。

简单来说，Pandoc 的工作流程分为两步：

输入格式 → 解析为 AST
AST → 渲染为输出格式

这种架构带来的直接好处是：任何能被 AST 完整表达的元素，就能"无损"地在支持该元素的目标格式之间流转。而转换损耗的本质，通常发生在两个环节——源格式的某些特性无法被完整解析进 AST，或者目标格式无法表达 AST 中的某些节点。

N×N 问题与中间表示层的工程智慧

Pandoc 采用 AST 作为中间表示层的架构设计，实际上解决了计算机科学中经典的 N×N 转换问题。如果 Pandoc 支持 N 种输入格式和 M 种输出格式，直接两两转换需要编写 N×M 个转换器。而通过引入统一的 AST 中间层，只需编写 N 个 Reader（解析器）和 M 个 Writer（渲染器），总工作量降至 N+M。这与编译器领域 LLVM 的设计理念一脉相承——LLVM 通过统一的中间表示（IR）连接多种前端语言和多种后端目标架构，实现了编译器组件的高效复用。Pandoc 目前支持超过 40 种输入格式和 60 种输出格式，如果采用直接转换方案将需要 2400 个转换器，而中间表示层将这一数字降至约 100 个模块，工程维护成本的差异不言而喻。

基于 AST 设计的标记语言转换保真度更高

一个关键发现值得强调：从设计之初就围绕清晰语法树构建的现代标记语言，在 Pandoc 转换中具有明显优势。

传统上，许多标记语言（尤其是早期 Markdown 的各种方言）语法定义模糊、边界情况处理不一致，解析结果难以标准化，转换时自然容易"失真"。而语法规则明确、解析结果可预测的语言，在与其他格式互转时保真度显著更高。

这也说明了一个重要原则：在评估"什么能在转换中幸存"时，语言的底层设计比表面语法更具决定性。

Markdown 的历史包袱与 Djot 的革新探索

从 Markdown 碎片化到 Djot 的诞生

Pandoc 的作者 John MacFarlane 同时也是 15 年前 Markdown 标准化工作的早期参与者之一。然而 Markdown 的"标准化"进程实际上演变成了相当程度的混乱——CommonMark、GitHub Flavored Markdown（GFM）、MultiMarkdown 等各种方言层出不穷，彼此之间存在微妙但恼人的语法差异。

Markdown 最初由 John Gruber 于 2004 年发布，其规范仅以一份非正式文档和一个 Perl 脚本实现的形式存在，缺乏形式化的语法定义。这导致了当输入包含嵌套列表缩进、行内 HTML 混合、链接引用嵌套等边界情况时，不同实现产生截然不同的输出。2014 年启动的 CommonMark 项目试图通过一份包含 600 多个测试用例的严格规范来解决这一问题，但其本身也引发了社区争议——Gruber 本人对"标准化"持保留态度，认为 Markdown 的灵活性正是其魅力所在。GFM 在 CommonMark 基础上增加了表格、任务列表、删除线等扩展，而 MultiMarkdown 则引入了脚注、元数据、数学公式等学术写作特性，这些方言的并存使得"Markdown 文件"实际上是一个语义模糊的概念。

CommonMark 规范的严格程度体现在其对解析优先级的精确定义上。例如，规范明确规定了当列表项、块引用和段落续行同时出现时的解析优先级顺序（即"懒惰续行"规则），以及强调标记的开启和关闭条件如何受到 Unicode 标点符号分类的影响。规范还定义了"分隔符运行"（delimiter run）的概念来处理连续 * 或 _ 字符的解析，这套规则复杂到需要专门的状态机来实现。正是这种复杂性促使 MacFarlane 在设计 Djot 时从根本上简化了强调标记的解析规则。

正是出于对这种碎片化的深刻反思，MacFarlane 近年来推出了 Djot——一个被定位为"Markdown 精神继承者"的新兴标记语言。Djot 试图在保留 Markdown 可读性优势的同时，彻底解决其语法歧义和解析不一致的历史包袱，提供一套更严谨、更适合机器精确处理的规则体系。

Djot 于 2022 年由 MacFarlane 正式提出，其设计遵循几个核心原则：首先，消除解析时的回溯需求——Markdown 中诸如强调标记（* 和 _）的解析需要复杂的回溯算法来确定开启与关闭位置，而 Djot 通过更明确的规则实现了近乎线性时间的解析。其次，Djot 严格区分了块级元素和行内元素的标记方式，避免了 Markdown 中列表项与段落之间暧昧不清的关系。第三，Djot 引入了通用属性语法（类似于 HTML 的 class 和 id），使得任何元素都能附加元数据而无需回退到原始 HTML。从实现角度看，Djot 的参考解析器以 Lua 编写，输出标准化的 AST 表示，其规范文档以形式化的方式定义了每条解析规则的优先级和适用条件。

Djot 实现近乎线性时间解析的关键在于消除了解析过程中的回溯（backtracking）。在传统 Markdown 解析中，遇到 * 字符时，解析器无法立即判断它是强调标记的开头还是普通字符，需要向前扫描寻找匹配的关闭标记，找不到时再回溯将其视为普通文本。在极端情况下（如大量未匹配的 * 字符），这种回溯可能导致指数级的时间复杂度，甚至被利用为正则表达式拒绝服务攻击（ReDoS）的变体。Djot 通过更明确的标记规则，使解析器在每个字符位置都能做出确定性的决策，从而保证了线性时间的解析性能。

理想标记语言需要平衡的三个维度

一门理想的标记语言应当在以下几个维度取得良好平衡：

可读性（Readability）：人类阅读纯文本源码时应当直观易懂
可写性（Writeability）：书写过程自然流畅，不额外增加认知负担
机器可消费性（Machine-consumable）：能被程序精确解析，不存在歧义

此外，它还需要足够全面，能够表达从离线文档到在线内容的各类元素。这三者之间天然存在张力——过度追求机器友好可能牺牲书写体验（如 XML 虽然机器解析友好，但人类书写和阅读的体验极差），而过度简化又会限制表达能力（如纯 Markdown 无法原生表达脚注、定义列表或数学公式等常见需求）。Djot 的出现正是这种平衡探索的一次实质性尝试，它试图证明严格的解析规则与优良的书写体验并非不可调和。

这三个维度的权衡在标记语言的历史中反复上演。从最早的 SGML（1986年ISO标准化）到 HTML、XML，再到 reStructuredText、AsciiDoc、Markdown 和如今的 Djot，每一代标记语言都在不同维度上做出了取舍。SGML 和 XML 将机器可消费性推到极致，代价是书写体验极其繁琐；Markdown 将可读性和可写性置于首位，却牺牲了规范的精确性；而 reStructuredText 和 AsciiDoc 虽然功能丰富但学习曲线较陡。理解这一历史脉络有助于我们评估 Djot 等新语言究竟在哪些方面实现了真正的突破。

开发者实战指南：格式选择与转换最佳实践

用 Dogfooding 验证你的工具链

"Dogfooding"（吃自己的狗粮）是检验工具可靠性的最佳方式——在实际项目中亲自使用你所推崇的格式和工具。只有当你真正用某种标记语言撰写文档、经历转换流程、面对实际损耗时，才能真正理解它的优势与局限所在。这一理念在软件行业有着深厚的传统——据传该术语源自 1988 年微软经理 Paul Maritz 发送的一封邮件，鼓励团队更多地使用自家产品。在文档转换场景中，dogfooding 意味着定期执行"往返测试"（roundtrip test）：将文档从格式 A 转换为格式 B，再转换回格式 A，然后对比两个版本 A 之间的差异。这种测试能够精确量化转换损耗的程度和类型。

降低 Pandoc 转换损耗的实用建议

对于日常需要处理文档格式转换的开发者与内容创作者，以下策略可以显著提升转换质量：

优先选择语法规则清晰的格式：如果内容需要频繁转换，选择解析规则明确的语言（如 CommonMark 或 Djot）能大幅降低损耗风险
提前了解 AST 的表达边界：转换前，先确认源格式和目标格式各自支持哪些元素，避免使用无法被目标格式表达的特性。例如，Markdown 的表格语法在转换为纯文本时会丢失对齐信息，而脚注在转换为不支持脚注的格式时可能被降级为括号注释。Pandoc 提供了 --list-input-formats 和 --list-output-formats 命令来查看支持的格式列表，更精细的元素支持情况则需要查阅各个 Reader 和 Writer 的文档
建立可复现的转换流程：善用 Pandoc 的模板和过滤器（filter）机制，让复杂转换变得可控、可维护、可追溯。Pandoc 的过滤器本质上是对 AST 进行变换的程序：Pandoc 将解析后的 AST 以 JSON 格式传递给外部过滤器程序，过滤器对其进行修改后返回新的 AST，Pandoc 再将修改后的 AST 渲染为目标格式。这种"管道式"架构允许用户在不修改 Pandoc 核心代码的情况下实现复杂的文档变换。Pandoc 支持两种过滤器接口：传统的 JSON 过滤器（可用任何语言编写）和性能更优的 Lua 过滤器（内嵌在 Pandoc 进程中运行，避免了 JSON 序列化的开销）

Pandoc 选择 Lua 作为内嵌过滤器语言同样经过深思熟虑。Lua 是一种专为嵌入式场景设计的轻量级脚本语言，其解释器仅约 200KB，可以直接链接到 Pandoc 的 Haskell 运行时中。相比 JSON 过滤器需要将整个 AST 序列化为 JSON、通过管道传递给外部进程、再将修改后的 JSON 反序列化回 AST 的过程，Lua 过滤器直接在 Pandoc 进程内存空间中操作 AST 数据结构，避免了序列化开销和进程间通信延迟。在处理大型文档时，这一性能差异可能达到数量级。Pandoc 社区已经积累了丰富的 Lua 过滤器生态，涵盖学术引用管理（如 citeproc）、图表生成、多语言排版等各种场景。

始终保留纯文本源文件：无论最终输出 HTML、PDF 还是 DOCX，都应以可读的纯文本标记源作为"单一真相源"，这才是内容长期价值的根本保障

将纯文本标记文件作为"单一真相源"（Single Source of Truth）的理念源自软件工程中的版本控制实践。与 DOCX 或 PDF 等二进制格式不同，纯文本文件可以被 Git 等版本控制系统高效地跟踪差异、合并变更和审查历史。这意味着文档的每一次修改都有完整的审计轨迹，多人协作时的冲突可以通过标准的 diff/merge 工具解决。此外，纯文本格式不依赖任何特定软件即可打开和编辑，具有极高的长期可读性——20 年前的纯文本文件今天依然可以轻松阅读，但 20 年前的专有格式文件可能已经无法打开。这种"面向未来"的特性对于学术出版、法律文档、技术文档等需要长期保存的内容尤为重要。

现代文档工作流中，基于 Git 的协作模式允许团队使用 Pull Request/Merge Request 对文档变更进行代码审查式的评审，每行修改都可以被逐一讨论和批准。GitHub 和 GitLab 等平台还能直接渲染 Markdown 文件的差异视图，使非技术人员也能参与审查。此外，通过 Git Hooks 或 CI/CD 管道，可以在文档提交时自动运行拼写检查、链接验证、样式一致性检查，甚至触发自动构建生成 PDF 或网站。这种"文档即代码"（Docs as Code）的理念已被 Google、Microsoft 等科技巨头广泛采用于其技术文档管理中。

标记语言仍在演进，理解转换逻辑至关重要

Pandoc 3.10.2 的发布再次提醒我们，文档格式转换远非一个已经解决的问题。Markdown 十五年来的碎片化演变说明标准化之路充满曲折，而 Djot 等新语言的涌现则展示了社区对更优方案的不懈追求。

无论你是内容创作者还是开发者，理解"什么能在转换中幸存"以及背后的 AST 设计哲学，都能帮助你在纷繁的标记语言生态中做出更明智的选择。那个完美平衡可读、可写与可机读的标记语言或许仍在路上，但每一次探索都在推动整个文档工具生态稳步向前。