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 commonmarkfenced_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)这段代码的含义是当文本中出现连续三个冒号:::: : : : : : cs时且当前输出格式启用了Ext_fenced_divs例如markdown、commonmarkfenced_divs变体在第一个冒号前插入反斜杠\同时用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要点如下冒号数量随嵌套加深基础冒号数为 3每嵌套一层加 13 divNesting。这就是手册中嵌套示例里内层::: Danger用 3 个冒号、外层用更多冒号的原因——围栏层数对应 Div 嵌套深度。属性必须输出打开围栏必须携带属性attrsToMd/classOrAttrsToMarkdown以区分打开与关闭围栏。classOrAttrsToMarkdown见 Markdown.hs在属性仅为单一 class 时输出裸单词否则回退到attrsToMarkdown输出花括号属性。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分支回退:::便只能作为普通文本参与段落解析。配套的divFenceEndMarkdown.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 commonmarkfenced_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 commonmarkfenced_divs两者的期望输出均为\::: A \:::作为对照可以验证转义仅在扩展启用时发生# 关闭 fenced_divs 后不再需要转义 printf :::\nA\n:::\n | pandoc -t markdown-fenced_divs此时:::在目标格式中没有任何特殊含义输出中不会再出现反斜杠。七、实战建议规避与利用这条规则结合以上分析可以得出几条可直接落地的实践建议写 Markdown 时避免裸:::行首既然至少三个冒号且无属性的裸行在fenced_divs下不会被解析为 Div但会在回写时被转义、在跨工具流转时可能产生歧义最稳妥的做法是在正文中避免以连续三个及以上冒号开头的行确有需要时用反斜杠转义或包裹在代码块中。理解Div围栏的必须带属性约束打开围栏必须携带{#id .class keyval}属性或裸 class 名否则不构成 Div。这既是语法约束也是阅读器区分围栏与普通文本的唯一依据。嵌套 Div 的冒号计数写入器按嵌套深度递增冒号数量3 嵌套层数手写多层嵌套时应模仿这一规则避免围栏边界错位。格式往返前先确认扩展集合markdown、commonmark等变体的默认扩展集合不同见 Extensions.hs 等默认集合定义同一段文档在不同变体间往返时:::的处理结果可能不同做文档转换流水线时应固定目标变体并做往返测试。把回归测试当作文档的一部分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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc 的 fenced divs 与 `:::` 转义机制：回归测试 11571 深度剖析
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 commonmarkfenced_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)这段代码的含义是当文本中出现连续三个冒号:::: : : : : : cs时且当前输出格式启用了Ext_fenced_divs例如markdown、commonmarkfenced_divs变体在第一个冒号前插入反斜杠\同时用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要点如下冒号数量随嵌套加深基础冒号数为 3每嵌套一层加 13 divNesting。这就是手册中嵌套示例里内层::: Danger用 3 个冒号、外层用更多冒号的原因——围栏层数对应 Div 嵌套深度。属性必须输出打开围栏必须携带属性attrsToMd/classOrAttrsToMarkdown以区分打开与关闭围栏。classOrAttrsToMarkdown见 Markdown.hs在属性仅为单一 class 时输出裸单词否则回退到attrsToMarkdown输出花括号属性。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分支回退:::便只能作为普通文本参与段落解析。配套的divFenceEndMarkdown.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 commonmarkfenced_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 commonmarkfenced_divs两者的期望输出均为\::: A \:::作为对照可以验证转义仅在扩展启用时发生# 关闭 fenced_divs 后不再需要转义 printf :::\nA\n:::\n | pandoc -t markdown-fenced_divs此时:::在目标格式中没有任何特殊含义输出中不会再出现反斜杠。七、实战建议规避与利用这条规则结合以上分析可以得出几条可直接落地的实践建议写 Markdown 时避免裸:::行首既然至少三个冒号且无属性的裸行在fenced_divs下不会被解析为 Div但会在回写时被转义、在跨工具流转时可能产生歧义最稳妥的做法是在正文中避免以连续三个及以上冒号开头的行确有需要时用反斜杠转义或包裹在代码块中。理解Div围栏的必须带属性约束打开围栏必须携带{#id .class keyval}属性或裸 class 名否则不构成 Div。这既是语法约束也是阅读器区分围栏与普通文本的唯一依据。嵌套 Div 的冒号计数写入器按嵌套深度递增冒号数量3 嵌套层数手写多层嵌套时应模仿这一规则避免围栏边界错位。格式往返前先确认扩展集合markdown、commonmark等变体的默认扩展集合不同见 Extensions.hs 等默认集合定义同一段文档在不同变体间往返时:::的处理结果可能不同做文档转换流水线时应固定目标变体并做往返测试。把回归测试当作文档的一部分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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考