如何用Lua过滤器实现Quarto Markdown标题与文件名同步？

问题场景 #

编写Quarto Markdown文档生成PDF时，希望输出文件名与文档标题保持一致，但每次重复填写title和format.pdf.output-file字段过于繁琐。想通过Lua过滤器直接引用title的值自动设置output-file，不确定能否访问并修改meta.format.pdf['output-file']。

可行方案 #

你的思路完全可行，Lua过滤器可以直接访问并修改Quarto的元数据结构，包括format.pdf下的配置项。以下是验证有效的实现方案：

1. 编写Lua过滤器文件 #

创建set-output-file.lua文件，内容如下：

-- file: set-output-file.lua
function Meta(meta)
  if meta.title then
    -- 提取标题纯文本，清理LaTeX命令、特殊字符，替换空格为下划线生成合法文件名
    local filename = pandoc.utils.stringify(meta.title)
    filename = filename:gsub("\\%a+", "")  -- 移除LaTeX格式命令（如\Large、\textbf）
                      :gsub("[^%w%s]", "") -- 移除非字母数字、非空格的特殊字符
                      :gsub("%s+", "_")    -- 把连续空格替换为下划线

    -- 确保format和format.pdf层级存在，避免nil引用报错
    if not meta.format then meta.format = pandoc.MetaMap({}) end
    if not meta.format.pdf then meta.format.pdf = pandoc.MetaMap({}) end

    -- 设置PDF输出文件名
    meta.format.pdf['output-file'] = filename
  end
  return meta
end

2. 在Quarto文档中使用过滤器 #

修改文档的YAML元数据，添加过滤器引用，无需手动填写output-file：

---
title: "\Large \textbf{Awesome title but Hanc marginis exiguitas non caperet}"
format:
  pdf:
    output-ext: "pdf"
filters:
  - set-output-file.lua
---

foo bar

关键说明 #

• pandoc.utils.stringify(meta.title)：将带有LaTeX格式的标题转换为纯文本，忽略格式命令。
• 字符串清理逻辑：确保生成的文件名符合系统命名规则，避免特殊字符导致的文件创建错误。
• 元数据层级检查：先创建meta.format和meta.format.pdf结构，防止直接赋值时出现nil引用错误。
• 过滤器执行时机：Lua过滤器在Quarto处理元数据阶段运行，修改后的output-file会被Quarto直接用于生成PDF文件。

内容的提问来源于stack exchange，提问作者Carlos Luis Rivera