Quarto Lua 过滤器系统全解析:多阶段 AST 管线、用户过滤器注入机制与调试实战
Quarto Lua 过滤器系统全解析:多阶段 AST 管线、用户过滤器注入机制与调试实战
Quarto 的 Lua 过滤器系统是一套围绕 Pandoc AST 构建的多阶段文档转换管线,由 src/resources/filters/ 目录下约 212 个 Lua 文件协作完成。本文以 .claude/rules/filters/overview.md 为骨架,结合 main.lua、emulatedfilter.lua 与 filters.ts 等源码,讲清七个阶段的执行顺序、用户过滤器在 filters YAML 键下的真实落点(entry point 拼接机制),并给出源码级的调试手段。读完你将能定位"某个过滤器到底在哪个阶段运行、何时运行",并掌握用 show-ast-trace / make-ast-diagram 可视化 AST 变换的实战方法。
一、系统概览:一条过滤器链,而非多个独立 Pandoc 过滤器
与直觉相反,Quarto 的 Lua 过滤器并不是多个独立的 pandoc --lua-filter 传参并列运行,而是在 main.lua 中维护一条单一过滤器列表(filter list),由 run_as_extended_ast() 统一驱动整条链的顺序执行(见 main.lua)。
这套系统有四个关键设计:
- 多阶段组织:过滤器按职责分成 INIT、NORMALIZE、PRE、CROSSREF、LAYOUT、POST、FINALIZE 七个阶段,每一阶段对应一个目录与一组具名过滤器条目。
- 全局状态先行:
main.lua首行通过import("./mainstateinit.lua")引入全局状态初始化模块,建立quarto_global_state、crossref.categories(图表、列表、注记等交叉引用分类表)等运行时数据结构(见 mainstateinit.lua)。 - 文本拼接式加载:过滤器文件之间用自定义的
import()(内部即dofile)进行文本级拼接,而可复用模块走require();这与 Pandoc 标准 Lua 过滤器单文件执行的模型截然不同,也是理解该目录组织方式的起点。 - Pandoc 解析之后才运行:整条管线处理的是 Pandoc 解析完毕的 AST;把原始
.qmd文本变成 AST 的工作由独立的 qmd 自定义 reader 完成,详见下文第五节。
二、目录结构逐层解读
src/resources/filters/ 的顶层布局对应管线的各个阶段与支撑设施(目录均已在仓库中确认存在):
filters/
├── main.lua # 入口:过滤器链定义(约 725 行)
├── mainstateinit.lua # 全局状态初始化(quarto_global_state、crossref.categories)
├── qmd-reader.lua # 自定义 Pandoc reader 的薄入口(非过滤器)
├── ast/ # 自定义 AST 基础设施(scopedwalk、emulatedfilter、customnodes、
│ # parse/render/runemulation/traceexecution/wrappedwriter 等)
├── common/ # 共享工具(约 35 个文件:log、debug、format、options、meta 等)
├── modules/ # 可复用模块(36 个 *.lua,经 require() 引入,import_all.lua 统一注册)
├── customnodes/ # 自定义节点实现(callout、proof、theorem、shortcodes、panel-tabset 等)
├── quarto-init/ # 初始化阶段(configurefilters、includes、resourcerefs、knitr-fixup、metainit)
├── normalize/ # 归一化阶段(normalize、flags、astpipeline、capturereaderstate、draft)
├── quarto-pre/ # 预处理(shortcodes、tables、code annotations、hidden、theorems 等 36 文件)
├── crossref/ # 交叉引用系统(figures、tables、equations、theorems、sections、index 等)
├── layout/ # 布局处理(columns、panels、figures、lightbox,以及各格式的 layout)
├── quarto-post/ # 后处理(格式相关渲染:latex、html、typst、reveal、email 等 30 文件)
└── quarto-finalize/ # 最终清理(dependencies、mediabag、meta-cleanup、book-cleanup 等)
关键目录职责
ast/是整个自定义节点系统的根基:customnodes.lua定义节点体系,scopedwalk.lua提供可感知自定义节点的遍历器,emulatedfilter.lua负责把用户过滤器包装并注入过滤器链(详见第四节)。common/是各阶段共用的工具集,其中log.lua(日志)、debug.lua(dump/tdump调试输出)、format.lua(输出格式检测)、options.lua(元数据选项读取)是编写过滤器时最常打交道的四个模块。customnodes/中每个文件对应一种 Quarto 独有的 AST 节点扩展,例如callout.lua(提示框)、proof.lua/theorem.lua(证明与定理)、shortcodes.lua(短代码)、floatreftarget.lua(浮动对象引用目标)。
三、过滤器执行管线:七个阶段的完整顺序
原文档定义的执行顺序如下(标注了每个阶段的职责):
1. INIT (quarto-init/)
↓
2. NORMALIZE (normalize/)
↓
3. PRE (quarto-pre/) - shortcodes, tables, code annotations
↓
4. CROSSREF (crossref/) - cross-references
↓
5. LAYOUT (layout/) - panels, columns
↓
6. POST (quarto-post/) - format-specific rendering
↓
7. FINALIZE (quarto-finalize/) - cleanup, dependencies
这一顺序在 main.lua 中由 quarto_init_filters(L229)、quarto_normalize_filters(L257)、quarto_pre_filters(L283)、quarto_crossref_filters(L671)、quarto_layout_filters(L631)、quarto_post_filters(L428)、quarto_finalize_filters(L583)七个具名表逐一 tappend 进 quarto_filter_list 而得到,阶段间还嵌入了多个具名 entry point 空位(见第四节)。
各阶段在源码中的真实映射
- INIT:
quarto_meta_init()、元数据资源引用(file_metadata()+resourceRefs())、knitr 语法修复(仅当param("execution-engine") == "knitr"时启用)。 - NORMALIZE:
normalize_draft()、normalize_filter()、normalize_capture_reader_state(),并追加quarto_ast_pipeline()。源码注释明确说明:v1.4 起 NORMALIZE 负责产出"归一化文档",因此用户过滤器看到的是 Quarto AST——例如Figure节点已不再存在,而是由自定义 AST 设施中的FloatRefTarget表示(见 main.lua)。这一点对用户过滤器作者极其重要:不要假设Figure节点仍存在。 - PRE:这一阶段条目最多,覆盖短代码(
shortcodes_filter(),受flags = {"has_shortcodes"}门控)、表格题注(table_captions())、代码注解(code_annotations())、隐藏内容(combineFilters({hidden(), content_hidden()}))、字体回退(normalize_font_fallbacks())、作用域元素解析(resolve_scoped_elements())等。 - CROSSREF:受
param("enable-crossref", true)控制(L227),启用时插入quarto_crossref_filters,处理浮动对象、定理、章节、方程、表格的引用解析与索引写入(resolveRefs()、writeIndex())。 - LAYOUT:
columns_preprocess()→columns()→cites_preprocess()→cites()→layout_panels(),负责面板、分栏、引文与灯箱(lightbox(),受has_lightbox门控)。 - POST:格式相关的渲染与修复全部集中于此——
render_latex()、render_typst()、render_dashboard()、render_asciidoc()、render_email()、render_reveal_fixups()、render_html_fixups()等,多数通过filterIf(...)或 flags 按格式与文档特征条件启用。 - FINALIZE:
mediabag_filter()、bookCleanup()、writeCites()、metaCleanup()、dependencies()与wrapped_writer(),负责依赖收集、媒体包整理、元数据清理与最终的 writer 包装。
flags:阶段级裁剪机制
留意到许多条目带有 flags 字段(如 has_notes、has_hidden、has_shortcodes、has_font_fallback)。这些 flag 由 normalize/flags.lua 的 compute_flags() 在 PRE 阶段早期计算(其第二返回表持有 Meta 处理器),随后 runemulation.lua 在整个过滤器趟(pass)都无任何 flag 命中时直接跳过该趟遍历。这是 Quarto 对"昂贵但多数文档用不到"的过滤器做的性能裁剪,比在过滤器函数内部提前 return 更彻底。
四、用户过滤器到底落在哪里:entry point 拼接机制
原文档最核心的结论是:用户通过 YAML filters 键声明的过滤器并不是独立的 Pandoc 过滤器趟,而是被"拼接"进 main.lua 的单一过滤器列表,落在其跟随的具名 marker(entry point)处。
两条注入规则
- 普通
filters条目落在pre-quarto:在 Quarto 所有阶段(PRE、CROSSREF、LAYOUT、POST)之前运行。 quartomarker 之后的条目落在post-render:filters列表中出现字面量quarto时,列表在此处被切开,其后所有条目移动到post-renderentry point,即 POST 之后、FINALIZE 之前运行。- FINALIZE 恒在两者之后:因为
post-render在过滤器列表中的位置天然早于 FINALIZE 各条目,所以无论用户过滤器落在pre-quarto还是post-render,FINALIZE 都保证最后执行。
TypeScript 侧:entry point 的生成
YAML 中的 filters 列表由 filters.ts 的 extractFilterSpecParams() 转换为结构化 entry point 描述:
- 若列表中存在
quarto,则其之前的普通条目发往kQuartoPre(即pre-quarto),之后的发往kQuartoPost(即post-render); - 若无
quarto,所有普通条目一律发往kQuartoPre; - 已具 entry point 形式的条目(带
at字段)原样保留; - 字符串条目按后缀判定类型:以
.lua结尾为"lua",否则为"json"; - citeproc 恒在最后运行。
最终产物形如 {"at": "pre-quarto", "type": "lua", "path": "my-filter.lua"},经 filterParamsJson() 组装进 QUARTO_FILTER_PARAMS 传给 Pandoc(L128、L183-L187)。
Lua 侧:字面插入而非独立执行
在 emulatedfilter.lua 中,inject_user_filters_at_entry_points(filter_list) 被 main.lua 调用:
- 读取
param("quarto-filters").entryPoints,逐条取出at字段; - 在
quarto_filter_list中按名字查找对应 entry point 的索引; - 用
table.insert(filter_list, index, filter)做字面位置插入——这与文档所述"不是独立执行模式,只是同一列表中的位置"完全一致; - 插入的条目被命名为
<entry-point>-user-<n>,并强制指定traverser = 'walk'(注释说明:使用默认 walk 遍历而非惰性 jog,避免用户过滤器在某些场景下行为异常); - 若 entry point 名字在列表里找不到,会
warn提示并回退到pre-quarto。
main.lua 中的完整 entry point 清单
main.lua 中通过 table.insert(quarto_filter_list, { name = ..., filter = {} }) 预置了 8 个具名空位,它们是用户过滤器的全部合法落点:
| entry point | 位置 | 适用场景 |
|---|---|---|
pre-ast |
INIT 之前 | 在 Quarto 任何阶段之前、且早于初始化 |
post-ast |
INIT、NORMALIZE 之后,PRE 之前 | 需要在归一化之后介入 |
pre-quarto |
PRE 之前 | 普通 filters 条目的默认落点 |
post-quarto |
PRE/CROSSREF/LAYOUT 之后 | 需要看到 Quarto 阶段处理结果 |
pre-render |
LAYOUT、POST 之前 | 渲染前介入 |
post-render |
POST 之后、FINALIZE 之前 | quarto marker 之后条目的落点 |
pre-finalize |
FINALIZE 之前 | 清理阶段前介入 |
post-finalize |
FINALIZE 之后 | 整个管线的最后钩子 |
实战配置示例
# 普通写法:my-filter.lua 落在 pre-quarto(在 PRE/CROSSREF/LAYOUT/POST 之前运行)
filters:
- my-filter.lua
# 带 quarto marker:my-first.lua 落在 pre-quarto,my-second.lua 落在 post-render
filters:
- my-first.lua
- quarto
- my-second.lua
# entry point 显式写法(与源码中 QuartoFilterEntryPoint 结构对应)
filters:
- at: post-render
type: lua
path: my-filter.lua
五、与 Pandoc 解析阶段的关系:qmd reader 是前置的"另一个世界"
需要特别强调:上述整条管线运行于 Pandoc 解析出 AST 之后。把原始 .qmd 文本变成 AST 的是 Quarto 的自定义 Lua reader(qmd-reader.lua 及 src/resources/pandoc/datadir/readqmd.lua),它:
- 在独立的 Lua 上下文中运行,过滤器链中的全局量(如
crossref.categories)在其中不存在; - 通过文档元数据与
param(...)与过滤器通信; - 在解析前做原始文本变换(短代码编码、fenced-code 转义),遵循"转义—还原"模式。
在 pandoc.ts 中,每次 Pandoc 调用前 Quarto 都会把 --from 强制设为 filters/qmd-reader.lua,同时把用户原本的 from 值保存为 user-defined-from 参数供 reader 内部参考。因此:凡是需要在 Pandoc 解析行为层面改变的东西(例如新的语法糖、块级语法),必须改 reader 而不是过滤器。读者可进一步阅读 llm-docs/qmd-reader-architecture.md 了解该阶段的完整架构。
六、关键文件一览
| 文件 | 用途 |
|---|---|
| main.lua | 过滤器链定义(约 725 行):全部 import、七阶段过滤器表、8 个 entry point 空位 |
| mainstateinit.lua | 全局状态初始化:quarto_global_state、crossref.categories |
| ast/customnodes.lua | 自定义节点系统(节点类型、_quarto.ast.walk 遍历入口) |
| ast/emulatedfilter.lua | 用户过滤器包装与 entry point 注入实现(table.insert 字面插入) |
| ast/runemulation.lua | 扩展 AST 模拟执行,按 flags 跳过整趟遍历 |
| common/log.lua | 日志工具(info/warn/error,warn 在 TypeScript 侧显示为 INFO) |
| common/debug.lua | 调试工具(dump、tdump) |
| common/format.lua | 输出格式检测(HTML/LaTeX/Typst/DOCX/Reveal.js/Dashboard) |
| common/options.lua | 元数据选项读取(option()),与 param() 配合 |
| normalize/flags.lua | 文档特征 flag 计算(has_notes、has_hidden 等) |
面向过滤器开发者的关键约定(摘要)
若你打算为 Quarto 编写 Lua 过滤器,.claude/rules/filters/lua-development.md 中还有一批与本节紧密相关的硬性约定,其中最容易踩坑的几条:
import()只用于过滤器文件,require()只用于modules/模块;在import()的文件中优先通过_quarto.modules.<name>.<fn>(...)引用已注册模块,避免新增顶层local变量触及 Lua 单函数 200 局部变量上限(详见 llm-docs/lua-filter-bundle-local-limit.md)。- 自定义节点遍历必须用
_quarto.ast.walk(),pandoc.walk_block会漏掉自定义节点。 - 格式门控要放在元素函数内部,而不是过滤器构造函数顶部:
main.lua在加载期(输出格式尚未解析)就调用构造函数,构造函数顶部的if not _quarto.format.isLatexOutput() then return {} end会提前求值成空过滤器,导致过滤器对任何文档都不生效(参考 quarto-pre/font.lua)。 - 昂贵过滤器用
flags门控整趟遍历,而不是在函数内提前 return。 - 过滤器返回值语义:返回
nil表示"继续、不改动",返回新元素表示"替换",返回空列表{}表示"删除该元素"。
参数传递:param() 与 QUARTO_FILTER_PARAMS
过滤器内部读取配置用 param("my-key", default)(如 param("enable-crossref", true)、param("execution-engine"))。该机制经 QUARTO_FILTER_PARAMS 环境变量(base64 编码的 JSON)从 TypeScript 侧传入,在 src/resources/pandoc/datadir/init.lua 中解码,对 Pandoc 模板与元数据完全不可见、不造成污染(详见 .claude/rules/filters/filter-params.md)。
七、调试与可视化:追踪 AST 在每个阶段的变换
过滤器调试的痛点在于"看不见 AST 在链中如何变化"。Quarto 为此提供了两个 dev-call 子命令(用法细节见 .claude/rules/dev-tools/dev-call-commands.md):
show-ast-trace:交互式追踪查看器
package/dist/bin/quarto dev-call show-ast-trace document.qmd
package/dist/bin/quarto dev-call show-ast-trace document.qmd --to html
执行流程:渲染文档并开启 AST 追踪 → 在缓存目录生成 <basename>-quarto-ast-trace.json → 在浏览器中启动交互式查看器。它适合回答"某个元素在第几个阶段被改成了什么"这类问题。
局限性:对 website/book 这类多文件项目支持不佳(环境变量无法按文件区分),且只展示 Pandoc 过滤器链的行为,不覆盖 postprocessor 与 writer 阶段。
make-ast-diagram:静态 AST 结构图
package/dist/bin/quarto dev-call make-ast-diagram document.qmd
package/dist/bin/quarto dev-call make-ast-diagram document.qmd --mode full
生成文档 Pandoc AST 的静态结构图,适合理解嵌套元素、排查复杂布局,比完整追踪更轻量。
备选:环境变量手动追踪
在常规渲染中设置 QUARTO_TRACE_FILTERS 环境变量即可开启追踪输出。完整的手动追踪指南见 dev-docs/lua-filter-trace-viewer.qmd。
八、延伸阅读
- 过滤器开发规范:.claude/rules/filters/lua-development.md(模块加载、自定义节点模式、格式检测、日志、外部命令执行等完整约定)
- qmd 自定义 reader(解析前阶段):llm-docs/qmd-reader-architecture.md(原始文本 → AST 的独立阶段,与过滤器链并行存在)
- 过滤器参数传递:.claude/rules/filters/filter-params.md(
param()与QUARTO_FILTER_PARAMS的完整链路) - 跨项目消费者:.claude/rules/filters/cross-project-consumers.md(部分过滤器被外部项目以独立
pandoc --lua-filter方式复用,删除前必须核查) - AST 追踪:dev-docs/lua-filter-trace-viewer.qmd
理解这条单一过滤器链及其 entry point 拼接机制,是深入 Quarto 渲染内核的第一步:它决定了任何用户过滤器的执行时机、可见的 AST 形态,以及能影响哪一阶段的产物——而这三点,正是调试一切渲染问题的关键坐标。
