企业官网建设流程全解析

Pandoc 的 fenced divs 与:::转义机制：回归测试 11571 深度剖析

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc

导读

在 pandoc 的 Markdown 语法中，:::是fenced_divs扩展定义的围栏 Div 分隔符。当文档中出现了本意是普通文本、却恰好以:::开头或包含连续冒号的内容时，Markdown 写入器在回写时必须将其转义为\:::，否则重新解析时会被误判为 Div 围栏，破坏文档结构。本篇文章以仓库中的命令回归测试 test/command/11571.md 为主线，结合阅读器、写入器的源码实现与官方手册，完整讲解这条转义规则的产生背景、实现原理与实战用法，帮助读者理解并避免这一隐蔽的 Markdown 往返（round-trip）陷阱。

一、问题背景：fenced_divs扩展与:::围栏语法

fenced_divs是 pandoc 的 Markdown 扩展之一，在 Extensions.hs 中定义为Ext_fenced_divs。启用该扩展后，可以用连续冒号围栏创建原生Div块：

::::: {#special .sidebar} Here is a paragraph. And another. :::::

按照 MANUAL.txt 的说明：

• Div 由至少三个连续冒号加上若干属性开始，属性之后可以（可选）再跟一串连续冒号；
• 属性语法与围栏代码块一致（Extension: fenced_code_attributes），既可以是花括号里的完整属性集，也可以是一个不带花括号的单词，后者会被当作 class 名；
• Div 以一行至少三个连续冒号结束，且建议与前后块之间用空行分隔；
• 打开围栏必须带属性——这是区分打开围栏与关闭围栏、以及区分普通文本的关键规则；
• 围栏 Div 可以嵌套，嵌套层数通过冒号数量体现。

例如手册中的嵌套示例：

::: Warning :::::: This is a warning. ::: Danger This is a warning within a warning. ::: ::::::::::::::::::

该扩展默认包含在markdown、commonmark等多个格式变体中（见 Extensions.hs 中extensionsFromList相关的默认集合配置）。

二、回归测试 11571：:::被当作普通文本时的回写转义

2.1 测试用例全文解读

仓库中的 test/command/11571.md 是一个命令式回归测试（golden test），全文只有两个用例，格式为：%开头的是命令行，^D之前的为输入，^D之后到下一个代码块之前的为期望输出。

第一个用例：

% pandoc -t markdown ::: A ::: ^D \::: A \:::

第二个用例：

% pandoc -t commonmark+fenced_divs ::: A ::: ^D \::: A \:::

2.2 测试在验证什么

输入文档只有三行：

::: A :::

由于fenced_divs要求打开围栏必须带有属性（参见 MANUAL.txt），单独一个裸:::并不构成 Div 的开头。因此这段输入在解析时被当作普通段落处理，三行合并为段落文本::: A :::。

问题出在回写（写出）阶段：markdown变体默认启用fenced_divs，如果写入器把段落原样输出为：

::: A :::

那么当这段输出再次被 pandoc 解析时，行首的:::极有可能被误认为是 Div 围栏，从而改变文档语义——这就是 issue #11571 描述的问题：写入器输出的:::意外触发了 Div 解析。

正确的输出是测试期望的：

\::: A \:::

即用反斜杠转义:::。这样重新解析时，\:::会被还原为字面文本:::，段落语义保持不变，实现了安全的 Markdown 往返。

2.3 变更记录佐证

在 changelog.md 中，Markdown 写入器一节的修复条目明确写着：

Escape:::to avoid triggering unintended divs (#11571).

这证实了 11571 是一个真实 issue，修复手段就是在写入器层面转义连续冒号。

三、源码级实现：写入器如何转义:::

3.1escapeText中的转义分支

转义逻辑位于 src/Text/Pandoc/Writers/Markdown/Inline.hs 的escapeText函数。该函数逐字符扫描普通文本内容（Str等行内元素），遇到特殊字符时插入反斜杠。其核心分支：

go (':':':':':':cs) | isEnabled Ext_fenced_divs opts -- see #11571 = '\\':':':':':': (takeWhile (==':') cs ++ go cs)

这段代码的含义是：

1. 当文本中出现连续三个冒号:::（':' : ':' : ':' : cs）时；
2. 且当前输出格式启用了Ext_fenced_divs（例如markdown、commonmark+fenced_divs变体）；
3. 在第一个冒号前插入反斜杠\；
4. 同时用takeWhile (==':') cs把后续连续的冒号一并吞掉，与前面的:::一起作为一个整体转义，最后递归处理剩余内容。

这样即使文本中有四个、五个乃至更多连续冒号，也会整体得到保护，不会残留未转义的冒号串。注意该分支只保护三个及以上连续冒号的场景，因为只有连续三个以上冒号才可能构成 Div 围栏；两个冒号不会触发 Div 解析，无需转义。

3.2 条件启用的设计考量

转义行为由isEnabled Ext_fenced_divs opts守卫，这意味着：

• 当输出格式不启用fenced_divs（例如markdown-fenced_divs）时，:::不会被转义，因为输出中不会存在 Div 围栏语法，:::天然就是普通文本；
• 当输出格式启用fenced_divs时，任何来自文档内容的:::都要被转义，避免与写入器自己生成的 Div 围栏混淆。

这种"仅在扩展启用时才转义"的设计，保证了转义动作既不会产生多余的噪音，也不会漏掉任何可能引发歧义的位置。

四、配套实现：写入器如何生成合法的 Div 围栏

转义只是"防御"一面，写入器在输出真正的Div块时，还有一套"进攻"逻辑，位于 src/Text/Pandoc/Writers/Markdown.hs 的blockToMarkdown'：

| isEnabled Ext_fenced_divs opts -> let attrsToMd = if variant == Commonmark then attrsToMarkdown opts else classOrAttrsToMarkdown opts divNesting = computeDivNestingLevel bs numcolons = 3 + divNesting colons = literal $ T.replicate numcolons ":" in nowrap (colons <+> attrsToMd attrs) $$ chomp contents $$ colons <> blankline

要点如下：

1. 冒号数量随嵌套加深：基础冒号数为 3，每嵌套一层加 1（3 + divNesting）。这就是手册中嵌套示例里内层::: Danger用 3 个冒号、外层用更多冒号的原因——围栏层数对应 Div 嵌套深度。
2. 属性必须输出：打开围栏必须携带属性（attrsToMd/classOrAttrsToMarkdown），以区分打开与关闭围栏。classOrAttrsToMarkdown（见 Markdown.hs）在属性仅为单一 class 时输出裸单词，否则回退到attrsToMarkdown输出花括号属性。
3. CommonMark 变体的差异：对于commonmark变体使用attrsToMarkdown，因为手册明确指出"commonmark 解析器不允许属性后跟冒号"，需要按 CommonMark 的围栏约束输出。

将这两套逻辑合起来看：写入器在输出Div时生成带属性的:::围栏；在输出普通文本遇到:::时则加反斜杠转义——一进一出，恰好保证了"围栏只属于 Div、文本永远是文本"。

五、阅读器端对应实现：为什么裸:::是文本

5.1 Markdown 阅读器的divFenced解析器

src/Text/Pandoc/Readers/Markdown.hs 中divFenced的定义清楚地解释了本测试输入为何被当作段落：

divFenced = do guardEnabled Ext_fenced_divs try $ do openpos <- getPosition string ":::" skipMany (char ':') skipMany spaceChar attribs <- attributes <|> ((\x -> ("",[x],[])) <$> takeWhile1P (\x -> x /= ' ' && x /= '\t' && x /= '\n' && x /= '\r')) ...

解析器在吃掉:::和可能的多余冒号之后，必须解析到属性（attributes，或一个非空白的裸单词作为 class）。如果:::之后直接是换行、没有属性，属性解析失败，整个try分支回退，:::便只能作为普通文本参与段落解析。

配套的divFenceEnd（Markdown.hs）用于识别关闭围栏：一行中:::加上任意数量的冒号，之后是空行或文件结尾。此外，阅读器还通过stateFencedDivLevel状态跟踪当前 Div 嵌套深度（Markdown.hs），并在blanklines'、notFollowedByDivCloser等辅助解析器中配合使用（Markdown.hs），确保块级解析不会跨越 Div 边界。

5.2 CommonMark 阅读器同样支持

commonmark阅读器在 src/Text/Pandoc/Readers/CommonMark.hs 中通过(fencedDivSpec <>)按Ext_fenced_divs是否启用，把围栏 Div 解析规格注入解析器列表。因此第二个测试用例-t commonmark+fenced_divs中，输入同样不会被识别为 Div，而是段落文本，回写时同样需要转义。

六、测试运行方式与验证

该测试属于 pandoc 的命令测试套件，与test/command/目录下其他数百个用例（如 test-pandoc.hs 所组织的命令测试）一同运行。若要手动复现，可在仓库构建出 pandoc 可执行文件后执行：

# 用例一：默认 markdown 变体 printf ':::\nA\n:::\n' | pandoc -t markdown # 用例二：commonmark + fenced_divs 变体 printf ':::\nA\n:::\n' | pandoc -t commonmark+fenced_divs

两者的期望输出均为：

\::: A \:::

作为对照，可以验证"转义仅在扩展启用时发生"：

# 关闭 fenced_divs 后，不再需要转义 printf ':::\nA\n:::\n' | pandoc -t markdown-fenced_divs

此时:::在目标格式中没有任何特殊含义，输出中不会再出现反斜杠。

七、实战建议：规避与利用这条规则

结合以上分析，可以得出几条可直接落地的实践建议：

1. 写 Markdown 时避免裸:::行首：既然"至少三个冒号且无属性"的裸行在fenced_divs下不会被解析为 Div，但会在回写时被转义、在跨工具流转时可能产生歧义，最稳妥的做法是在正文中避免以连续三个及以上冒号开头的行；确有需要时用反斜杠转义或包裹在代码块中。
2. 理解Div围栏的"必须带属性"约束：打开围栏必须携带{#id .class key=val}属性或裸 class 名，否则不构成 Div。这既是语法约束，也是阅读器区分"围栏"与"普通文本"的唯一依据。
3. 嵌套 Div 的冒号计数：写入器按嵌套深度递增冒号数量（3 + 嵌套层数），手写多层嵌套时应模仿这一规则，避免围栏边界错位。
4. 格式往返前先确认扩展集合：markdown、commonmark等变体的默认扩展集合不同（见 Extensions.hs 等默认集合定义），同一段文档在不同变体间往返时，:::的处理结果可能不同；做文档转换流水线时应固定目标变体并做往返测试。
5. 把回归测试当作文档的一部分：test/command/11571.md 这类极简测试用例直接给出了输入与期望输出的对应关系，是理解 pandoc 语义边界最权威、最简洁的参考材料，值得在排查格式问题时优先查阅。

八、总结

回归测试 11571 以两个极简用例锁定了一个容易被忽视的语义边界：当fenced_divs启用时，写入器必须把正文中的:::转义为\:::，否则文档在 Markdown 往返中会"凭空"生成 Div。这条规则在写入器端由 Inline.hs 的escapeText实现，在阅读器端由 Markdown.hs 的"打开围栏必须带属性"约束兜底，而写入器输出 Div 时的嵌套冒号计数（Markdown.hs）则保证了围栏语法的自洽。理解这一来一回两条路径，就能在文档转换、格式往返与自定义过滤器中准确预判:::的行为，避免踩中这一隐蔽陷阱。

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc