如何实现可读取文档内容的Quarto短码？以图片计数为例

Quarto的文档处理流程中，元素过滤器会先于短码执行，因此可以利用扩展的全局状态存储过滤器提取的文档信息，再让短码读取该状态并输出内容。以统计图片数量为例，具体实现步骤如下：

1. 用元素过滤器统计并存储数据 #

创建扩展的Lua过滤器文件（比如filters/imgcount.lua），在过滤器中统计文档内的图片数量，并将结果存入扩展专属的全局状态：

-- 初始化图片计数
local img_count = 0

-- 遍历所有图片元素并计数
function Image(el)
  img_count = img_count + 1
  return el
end

-- 文档处理完成前，将计数存入扩展元数据空间
function Pandoc(doc)
  quarto.doc.set_metadata("img-count", img_count, "extension")
  return doc
end

使用extension命名空间存储数据，可避免与用户文档的元数据产生冲突。

2. 定义短码读取状态并输出结果 #

在扩展的短码文件（比如shortcodes/imgcount.lua）中，读取之前存储的统计数据并输出：

function shortcode_imgcount(args, kwargs)
  -- 从扩展元数据中获取图片计数，默认值为0
  local count = quarto.doc.get_metadata("img-count", 0)
  return tostring(count) .. " 张图片"
end

-- 注册短码
return {
  ["imgcount"] = shortcode_imgcount
}

3. 配置扩展文件，同时加载过滤器与短码 #

在扩展的_extension.yml配置文件中声明要加载的过滤器和短码：

title: "Image Count Extension"
filters:
  - imgcount.lua
shortcodes:
  - imgcount.lua

核心原理说明 #

• Quarto的处理顺序是先执行所有元素过滤器，再解析并运行短码，因此过滤器统计的数据会提前存储完成，短码执行时可安全读取。
• 借助quarto.doc.set_metadata和quarto.doc.get_metadata的extension命名空间，能确保数据仅在当前扩展内部共享，不会影响文档的其他内容。

这种方式既发挥了过滤器访问文档内容的能力，又保留了短码的易用性，是Quarto扩展中实现此类需求的标准优雅方案。

内容的提问来源于stack exchange，提问作者Migwell