Pandoc AsciiDoc 输出中标题层级的等号映射规则解析——以命令测试 10062 为例【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandocPandoc 将 Markdown 转换为 AsciiDoc 时标题Header会从 Pandoc 内部层级映射为 AsciiDoc 的等号标记层级。本文以仓库命令测试 test/command/10062.md 为切入点结合 AsciiDoc Writer 源码 src/Text/Pandoc/Writers/AsciiDoc.hs完整讲解-t asciidoc输出标题的层级换算规则、新旧两套 AsciiDoc 写法的差异以及命令测试golden test的验证机制读完即可精确预测任意 Markdown 标题在 AsciiDoc 输出中的形态。一个命令测试10062.md 揭示了什么test/command/目录存放的是 pandoc 的命令测试command tests每个.md文件的第一行以%开头书写一条待执行的 pandoc 命令行其后的内容分为“输入”与“期望输出”两段由^D分隔最终由测试框架逐字比对实际输出与期望输出。该机制的定义位于 test/Tests/Command.hs如dropPercent与 golden 测试的组装逻辑。test/command/10062.md 全文如下% pandoc -t asciidoc ### section ##### five ^D section five它测试的是一个非常具体的转换场景用pandoc -t asciidoc处理两个 Markdown 标题——三级标题### section被输出为 AsciiDoc 的 section五级标题##### five被输出为 AsciiDoc 的 five。注意输出端的等号数量恰好比 Markdown 一侧多一个###3 个#→4 个#####5 个#→6 个。这正是 AsciiDoc 标题层级与 Pandoc 内部层级之间的核心换算规则下文从源码层面给出精确解释。AsciiDoc 标题语法与 Pandoc 的层级映射AsciiDoc 使用行首连续的表示标题层级是文档标题document title是章节标题、、、依次类推最多支持到六级。Pandoc 内部将标题表示为Header level其中 Markdown 的#对应 level 1、##对应 level 2依此类推。AsciiDoc Writer 在渲染标题时执行level 1的换算——Pandoc 的 level 1 标题输出为 AsciiDoc 的文档标题level 2 输出为……level 5 输出为。因此MarkdownPandoc 内部 levelAsciiDoc 输出等号数量#level 1 title1##level 2 title2###level 3 title3####level 4 title4#####level 5 title5######level 6 title610062.md 验证的正是该表中第 3 行与第 5 行的两个样本点属于这一映射规则的最小回归测试一旦 Writer 修改了标题渲染逻辑该测试就会因输出不符而失败。源码实现Header 渲染的核心逻辑标题映射规则的实现位于 src/Text/Pandoc/Writers/AsciiDoc.hs 的blockToAsciiDoc对Header的分支blockToAsciiDoc opts (Header level (ident,_,_) inlines) do contents - inlineListToAsciiDoc opts inlines ids - gets autoIds let autoId uniqueIdent (writerExtensions opts) inlines ids modify $ \st - st{ autoIds Set.insert autoId ids } let identifier if T.null ident || (isEnabled Ext_auto_identifiers opts ident autoId) then empty else [[ literal ident ]] return $ identifier $$ nowrap (text (replicate (level 1) ) space contents) blankline关键一行是replicate (level 1) 按level 1的数量重复生成字符后面跟一个空格与标题内容。### section进入 writer 时 level 为 3replicate 4 生成拼上section即得到 section——与 10062.md 的期望输出完全吻合。同一分支还展示了两个容易被忽略的细节标题标识符anchor当标题带有ident且未启用Ext_auto_identifiers或该 ident 恰好等于自动生成的 id时会在标题前输出[[ident]]形式的 AsciiDoc anchor否则不输出。这保证了交叉引用链接在 AsciiDoc 端可用。自动 id 登记writer 内部维护autoIds集合每次渲染标题都会调用uniqueIdent计算并登记用于处理多个同名标题时的 id 去重。此外src/Text/Pandoc/Writers/AsciiDoc.hs 对Div (, section:_, _)包裹的标题块例如从 HTML 转换而来时常见的 section 结构会先递归渲染标题再渲染块内其余内容保证章节容器中的标题层级同样遵循上述规则。两套 AsciiDoc 输出writeAsciiDoc 与 writeAsciiDocLegacyAsciiDoc 生态存在两个世代旧版 AsciiDocPython 实现asciidoc命令与 AsciiDoc 5asciidoctor。Pandoc 对此提供了两个 writer 入口定义于 src/Text/Pandoc/Writers/AsciiDoc.hswriteAsciiDoc :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDoc opts document ... -- | Deprecated synonym of writeAsciiDoc. writeAsciiDoctor :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDoctor writeAsciiDoc -- | Convert Pandoc to legacy AsciiDoc. writeAsciiDocLegacy :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDocLegacy opts document ...二者通过 writer 状态中的legacy :: Bool字段区分src/Text/Pandoc/Writers/AsciiDoc.hs默认legacy False在新旧语法存在分歧的环节如数学公式输出、部分块语法走不同的分支。writeAsciiDoctor已被标记为 deprecated统一改用writeAsciiDoc。需要特别说明的是标题层级的等号映射规则在两套 writer 中是一致的——legacy标志只影响如数学公式、属性语法等细节不影响replicate (level 1) 这条标题生成逻辑。因此无论目标工具是旧版asciidoc还是asciidoctorMarkdown###都会输出为。单元测试 test/Tests/Writers/AsciiDoc.hs 也分别用writeAsciiDocLegacy def与writeAsciiDoc def构造了asciidoc与asciidoctor两组测试辅助函数对两类输出同时做断言。实战如何验证与扩展这条规则验证 10062.md 的最直接方式是在命令行手工复现printf ### section\n\n##### five\n | pandoc -t asciidoc期望输出 section five也可以在项目测试体系中运行该命令测试由 test/Tests/Command.hs 负责解析%行、执行命令并与期望输出做 golden 比对不匹配即测试失败。test/command/目录下还有大量围绕 AsciiDoc 输出的回归测试可供交叉参考例如test/command/10105.mdpandoc -t asciidoc --wrappreserve验证换行策略对输出的影响test/command/11006.mdpandoc -f html -t asciidoc覆盖 HTML 输入路径下的 AsciiDoc 输出test/command/2337.mdpandoc -t asciidoc -f html同样验证 HTML 输入的转换test/command/5690.mdpandoc -f docbook -t asciidoc验证 DocBook 输入源test/command/6308.mdpandoc -f org -t asciidoc验证 Org 输入源。这些测试共同构成 AsciiDoc Writer 的行为护栏无论输入来自 Markdown、HTML、DocBook 还是 Org标题层级映射、代码块、表格等输出都必须保持稳定。若你正在编写需要嵌入 AsciiDoc 流水线如 Asciidoctor 文档生成的 Markdown 源文件牢记“Markdown 层级 1 AsciiDoc 等号数量”这一规则即可在写作阶段准确预判最终文档的标题结构避免出现层级跳变。小结从一条 8 行的命令测试出发本文完整还原了 Pandoc AsciiDoc 输出的标题映射机制Header level经replicate (level 1) 换算为 AsciiDoc 等号标记10062.md 验证了 level 3 与 level 5 两个样本点同一套规则同时适用于writeAsciiDoc与writeAsciiDocLegacy两条 writer 路径且由命令测试与单元测试双重守护。理解这条映射规则是可靠使用pandoc -t asciidoc产出规范 AsciiDoc 文档的第一步。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc AsciiDoc 输出中标题层级的等号映射规则解析——以命令测试 10062 为例
Pandoc AsciiDoc 输出中标题层级的等号映射规则解析——以命令测试 10062 为例【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandocPandoc 将 Markdown 转换为 AsciiDoc 时标题Header会从 Pandoc 内部层级映射为 AsciiDoc 的等号标记层级。本文以仓库命令测试 test/command/10062.md 为切入点结合 AsciiDoc Writer 源码 src/Text/Pandoc/Writers/AsciiDoc.hs完整讲解-t asciidoc输出标题的层级换算规则、新旧两套 AsciiDoc 写法的差异以及命令测试golden test的验证机制读完即可精确预测任意 Markdown 标题在 AsciiDoc 输出中的形态。一个命令测试10062.md 揭示了什么test/command/目录存放的是 pandoc 的命令测试command tests每个.md文件的第一行以%开头书写一条待执行的 pandoc 命令行其后的内容分为“输入”与“期望输出”两段由^D分隔最终由测试框架逐字比对实际输出与期望输出。该机制的定义位于 test/Tests/Command.hs如dropPercent与 golden 测试的组装逻辑。test/command/10062.md 全文如下% pandoc -t asciidoc ### section ##### five ^D section five它测试的是一个非常具体的转换场景用pandoc -t asciidoc处理两个 Markdown 标题——三级标题### section被输出为 AsciiDoc 的 section五级标题##### five被输出为 AsciiDoc 的 five。注意输出端的等号数量恰好比 Markdown 一侧多一个###3 个#→4 个#####5 个#→6 个。这正是 AsciiDoc 标题层级与 Pandoc 内部层级之间的核心换算规则下文从源码层面给出精确解释。AsciiDoc 标题语法与 Pandoc 的层级映射AsciiDoc 使用行首连续的表示标题层级是文档标题document title是章节标题、、、依次类推最多支持到六级。Pandoc 内部将标题表示为Header level其中 Markdown 的#对应 level 1、##对应 level 2依此类推。AsciiDoc Writer 在渲染标题时执行level 1的换算——Pandoc 的 level 1 标题输出为 AsciiDoc 的文档标题level 2 输出为……level 5 输出为。因此MarkdownPandoc 内部 levelAsciiDoc 输出等号数量#level 1 title1##level 2 title2###level 3 title3####level 4 title4#####level 5 title5######level 6 title610062.md 验证的正是该表中第 3 行与第 5 行的两个样本点属于这一映射规则的最小回归测试一旦 Writer 修改了标题渲染逻辑该测试就会因输出不符而失败。源码实现Header 渲染的核心逻辑标题映射规则的实现位于 src/Text/Pandoc/Writers/AsciiDoc.hs 的blockToAsciiDoc对Header的分支blockToAsciiDoc opts (Header level (ident,_,_) inlines) do contents - inlineListToAsciiDoc opts inlines ids - gets autoIds let autoId uniqueIdent (writerExtensions opts) inlines ids modify $ \st - st{ autoIds Set.insert autoId ids } let identifier if T.null ident || (isEnabled Ext_auto_identifiers opts ident autoId) then empty else [[ literal ident ]] return $ identifier $$ nowrap (text (replicate (level 1) ) space contents) blankline关键一行是replicate (level 1) 按level 1的数量重复生成字符后面跟一个空格与标题内容。### section进入 writer 时 level 为 3replicate 4 生成拼上section即得到 section——与 10062.md 的期望输出完全吻合。同一分支还展示了两个容易被忽略的细节标题标识符anchor当标题带有ident且未启用Ext_auto_identifiers或该 ident 恰好等于自动生成的 id时会在标题前输出[[ident]]形式的 AsciiDoc anchor否则不输出。这保证了交叉引用链接在 AsciiDoc 端可用。自动 id 登记writer 内部维护autoIds集合每次渲染标题都会调用uniqueIdent计算并登记用于处理多个同名标题时的 id 去重。此外src/Text/Pandoc/Writers/AsciiDoc.hs 对Div (, section:_, _)包裹的标题块例如从 HTML 转换而来时常见的 section 结构会先递归渲染标题再渲染块内其余内容保证章节容器中的标题层级同样遵循上述规则。两套 AsciiDoc 输出writeAsciiDoc 与 writeAsciiDocLegacyAsciiDoc 生态存在两个世代旧版 AsciiDocPython 实现asciidoc命令与 AsciiDoc 5asciidoctor。Pandoc 对此提供了两个 writer 入口定义于 src/Text/Pandoc/Writers/AsciiDoc.hswriteAsciiDoc :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDoc opts document ... -- | Deprecated synonym of writeAsciiDoc. writeAsciiDoctor :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDoctor writeAsciiDoc -- | Convert Pandoc to legacy AsciiDoc. writeAsciiDocLegacy :: PandocMonad m WriterOptions - Pandoc - m Text writeAsciiDocLegacy opts document ...二者通过 writer 状态中的legacy :: Bool字段区分src/Text/Pandoc/Writers/AsciiDoc.hs默认legacy False在新旧语法存在分歧的环节如数学公式输出、部分块语法走不同的分支。writeAsciiDoctor已被标记为 deprecated统一改用writeAsciiDoc。需要特别说明的是标题层级的等号映射规则在两套 writer 中是一致的——legacy标志只影响如数学公式、属性语法等细节不影响replicate (level 1) 这条标题生成逻辑。因此无论目标工具是旧版asciidoc还是asciidoctorMarkdown###都会输出为。单元测试 test/Tests/Writers/AsciiDoc.hs 也分别用writeAsciiDocLegacy def与writeAsciiDoc def构造了asciidoc与asciidoctor两组测试辅助函数对两类输出同时做断言。实战如何验证与扩展这条规则验证 10062.md 的最直接方式是在命令行手工复现printf ### section\n\n##### five\n | pandoc -t asciidoc期望输出 section five也可以在项目测试体系中运行该命令测试由 test/Tests/Command.hs 负责解析%行、执行命令并与期望输出做 golden 比对不匹配即测试失败。test/command/目录下还有大量围绕 AsciiDoc 输出的回归测试可供交叉参考例如test/command/10105.mdpandoc -t asciidoc --wrappreserve验证换行策略对输出的影响test/command/11006.mdpandoc -f html -t asciidoc覆盖 HTML 输入路径下的 AsciiDoc 输出test/command/2337.mdpandoc -t asciidoc -f html同样验证 HTML 输入的转换test/command/5690.mdpandoc -f docbook -t asciidoc验证 DocBook 输入源test/command/6308.mdpandoc -f org -t asciidoc验证 Org 输入源。这些测试共同构成 AsciiDoc Writer 的行为护栏无论输入来自 Markdown、HTML、DocBook 还是 Org标题层级映射、代码块、表格等输出都必须保持稳定。若你正在编写需要嵌入 AsciiDoc 流水线如 Asciidoctor 文档生成的 Markdown 源文件牢记“Markdown 层级 1 AsciiDoc 等号数量”这一规则即可在写作阶段准确预判最终文档的标题结构避免出现层级跳变。小结从一条 8 行的命令测试出发本文完整还原了 Pandoc AsciiDoc 输出的标题映射机制Header level经replicate (level 1) 换算为 AsciiDoc 等号标记10062.md 验证了 level 3 与 level 5 两个样本点同一套规则同时适用于writeAsciiDoc与writeAsciiDocLegacy两条 writer 路径且由命令测试与单元测试双重守护。理解这条映射规则是可靠使用pandoc -t asciidoc产出规范 AsciiDoc 文档的第一步。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考