Pandoc 与 Typst：解读 9585 测试用例中 unnumbered/unlisted 标题的转换逻辑

文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载本篇技术指南以 pandoc 仓库中的命令测试用例 test/command/9585.md 为主线深入剖析 Pandoc 的 Typst 写入器如何处理带有unnumbered不编号与unlisted不进目录类的标题。读者将掌握 Typst 写入器生成#heading(level: ..., outlined: false, numbering: none)的底层原理、这两个标题类在 Pandoc 全格式中的通用语义以及如何在 Markdown 源文档中实际使用这一能力。测试用例全貌一条命令、三段标题9585 号测试用例完整内容如下原文 11 行% pandoc -f native -t typst [ Header 2 ( , [] , [] ) [ Str One ] , Header 2 ( , [ unnumbered, unlisted ] , [] ) [ Str Two ] , Header 2 ( , [] , [] ) [ Str Three ] ] ^D One #heading(level: 2, outlined: false, numbering: none)[Two] Three这是 pandoc 标准的 golden test金标测试格式%开头是待执行的命令行^D之前的缩进内容是标准输入这里是 Pandoc 内部 AST 的 native 表示^D之后是期望的标准输出。用例输入了三段 level-2 标题Header 2它们的差异仅在第二个参数——属性列表class上标题类class期望输出One空 OneTwounnumbered,unlisted#heading(level: 2, outlined: false, numbering: none)[Two]Three空 Three可以看到关键行为普通标题直接输出 Typst 的标题语法一旦标题携带unnumbered或unlisted类写入器便切换为 Typst 函数式语法#heading(...)[...]并附加对应的属性参数。其中outlined: false对应unlisted类numbering: none对应unnumbered类。源码实现Typst 写入器如何构造#heading这一转换逻辑位于 Typst 写入器的核心块转换函数blockToTypst中见 src/Text/Pandoc/Writers/Typst.hsHeader level (ident,cls,kvs) inlines - do contents - inlinesToTypst inlines let lab case lookup typst-label kvs of Just l - toLabel FreestandingLabel l Nothing - toLabel FreestandingLabel ident let headingAttrs [outlined: false | unlisted elem cls] [numbering: none | unnumbered elem cls] return $ if null headingAttrs then nowrap (literal (T.replicate level ) space contents) cr lab else literal #heading parens (literal (T.intercalate , (level: tshow level : headingAttrs))) brackets contents cr lab从源码结构可以拆解出完整的生成规则属性收集headingAttrs是一个列表推导。当cls中包含unlisted时追加outlined: false包含unnumbered时追加numbering: none。两个条件彼此独立、可叠加——这正是测试用例中 Two 标题同时出现两个属性的原因。分支判断若headingAttrs为空即两个类都没有走 Typst 的语法糖重复的次数等于标题层级level否则输出#heading(...)[...]函数调用参数以level: N开头后跟收集到的属性列表。标签输出两种分支的末尾都会追加lab——标题的标签。标签优先取键值属性typst-label否则取标题的ident标识符通过toLabel FreestandingLabel生成用于 Typst 中的交叉引用。需要特别指出的是该分支仅在类列表非空且包含这两个类之一时触发如果标题只有其他类如自定义样式类而不含这两个类仍会输出语法。因此outlined: false与numbering: none的职责划分在写入器层面是明确且正交的前者剔除目录后者关闭编号。类的通用语义unnumbered 与 unlisted 是什么这两个类并非 Typst 写入器独有而是 Pandoc 全局的标题约定在 MANUAL.txt 中有明确说明unnumbered带此类的标题即使指定了--number-sections也永远不会被编号见 MANUAL.txt 中该选项的说明。unlisted若与unnumbered同时存在该标题不会进入目录table of contents。快捷写法属性上下文中的单个连字符{-}等价于{.unnumbered}在非英语文档中更推荐使用例如# My heading {-}。适用范围这一特性当前在部分格式LaTeX 系、HTML 系、PowerPoint、RTF中实现MANUAL.txt而 Typst 写入器同样实现了等价支持——9585 测试用例正是其验证证据。一个实际场景是参考文献章节当 Pandoc 在文档末尾插入参考文献列表时会自动为# References标题添加unnumbered类使文献章节不被编号MANUAL.txt。这与 9585 用例中展示的机制完全一致只是触发方不同——一个是写入器主动添加一个是用户显式标注。跨格式对比同一类在不同写入器中的落地对比另一个命令测试 test/command/1762.md可以看到同样三个标题在 LaTeX 写入器下的输出% pandoc -t latex # One {.unlisted} # Two {.unnumbered} # Three {.unlisted .unnumbered} ^D \section{One}\label{one} \section*{Two}\label{two} \addcontentsline{toc}{section}{Two} \section*{Three}\label{three}LaTeX 侧的映射是unnumbered产生星号命令\section*{}unlisted再通过\addcontentsline{toc}{section}{...}将标题从目录中剔除\section*默认不入目录故该行是反向恢复编号但保持不列出——实际效果是两者组合后标题不编号、不入目录。而 Typst 侧则统一收敛为#heading的两个属性。两种写入器的语法形态不同但语义模型一致编号与目录是标题的两个独立维度可分别关闭。这解释了为什么 test/command/10635.md 等其他用例也会同时携带unnumbered与unlisted两个类来测试组合场景。实战在 Markdown 中编写不编号、不入目录的标题将 9585 用例的结论落到日常写作在 Markdown 源文档中只需给标题追加类即可# 参与文献 {-}这等价于# 参与文献 {.unnumbered}转换到 Typst 输出为#heading(level: 1, numbering: none)[参与文献]若希望标题既不编号也不进目录# 附录 {.unnumbered .unlisted}输出为#heading(level: 1, outlined: false, numbering: none)[附录]注意类名顺序不影响结果——源码中的两个列表推导是独立判断的。无论哪种写法写入器都会为标题生成可引用的标签默认取自标题文本自动生成的标识符或显式指定的typst-label/ident因此在 Typst 文档中仍可通过label交叉引用这些标题。测试体系这类用例如何保障写入器行为9585 用例属于 pandoc 的命令测试套件由 test/test-pandoc.hs 驱动、test/Tests/Command.hs 实现执行框架读取test/command/目录下的NNNN.md文件解析出命令行与期望输出运行真实 pandoc 二进制并逐字比对。这意味着#heading(level: 2, outlined: false, numbering: none)的输出是受回归测试保护的约定——任何对blockToTypst中headingAttrs逻辑的修改都必须让该用例继续通过。同类用例如 test/command/1762.md、test/command/11795.md共同覆盖了不同写入器、不同标题组合下的行为矩阵是理解 Pandoc 各格式写入器语义差异的最佳入口。小结从 9585 这个 11 行的测试用例出发可以还原出 Pandoc 的一条完整技术链路Markdown 中的{.unnumbered .unlisted}类 → 内部 AST 的Header块属性 → Typst 写入器blockToTypst中的headingAttrs列表推导 → 最终输出#heading(level: 2, outlined: false, numbering: none)[...]。这条链路同时受 MANUAL.txt 的语义文档、Typst.hs 的源码实现与 test/command/ 的回归测试三重约束是理解 Pandoc 类驱动的跨格式标题控制机制的最小而完整的样本。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐Pandoc 标题类属性深度解析unnumbered 与 unlisted 在 LaTeX 输出中的行为机制Pandoc 标题类属性深度解析 unnumbered 与 unlisted 在 LaTeX 输出中的行为机制 本文基于 pandoc 仓库中的回归测试用例文档开发工具CLIPandoc 与 Typst 引号转义从测试用例 11463 解析 、 与 \ 的读写往返Pandoc 与 Typst 引号转义从测试用例 11463 解析 、 与 \ 的读写往返 本篇技术指南以 pandoc 仓库中的回归测试用例 te文档开发工具CLIpandoc Markdown 转义改进实战读懂命令测试 7726 中 \ 标题转义的保留逻辑pandoc Markdown 转义改进实战读懂命令测试 7726 中 \ 标题转义的保留逻辑 pandoc 是一款通用文档格式转换器其命令测试comma文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考