Quarto移除链接.html扩展示例生效，项目中失效求排查

以下是针对你的Quarto扩展在图书项目中失效的具体排查方向：

1. 验证过滤器执行时机与链接生成阶段的匹配性 #

Quarto图书的内部链接往往是在AST处理之后、HTML输出阶段才被自动添加上.html后缀的。如果你的Lua过滤器仅在AST的Link节点处理阶段运行，可能会错过后续生成的带.html的链接。

• 尝试改用PostProcess阶段处理：直接修改最终输出的HTML内容，而非仅处理AST节点。示例脚本：

  function postProcess(output)
      -- 替换所有href属性中的.html后缀（包含锚点、查询参数的情况）
      return output:gsub('href="([^"]+)%.html"', 'href="%1"')
  end
  

2. 调试过滤器的实际处理内容 #

在你的Link处理函数中添加日志输出，确认过滤器是否真的接触到了带.html的链接：

function Link(el)
    print("Original target:", el.target)
    local result = el.target:gsub("(.-)%.html(.-)", "%1%2")
    print("Modified target:", result)
    el.target = result
    return el
end

运行渲染命令时开启 verbose 模式：

quarto render --verbose

查看控制台输出，如果没有打印出带.html的target，说明过滤器运行时链接还未被添加后缀，需要调整执行时机。

3. 优化正则表达式的覆盖范围 #

当前正则(.-)%.html(.-)可能存在匹配不严谨的情况，比如无法覆盖.html位于链接末尾且无后续字符的场景，或者特殊路径格式。可以替换为更精确的正则：

-- 匹配.html结尾，或.html后紧跟锚点/查询参数的情况
local result = el.target:gsub("(.*)%.html([#?].*)?$", "%1%2")

4. 确保过滤器执行优先级最高 #

即使在配置中将自定义过滤器放在最后，仍可能被Quarto内置的图书处理逻辑覆盖。可以在扩展的_config.yml中明确指定执行顺序：

filters:
  - strip-dot-html-off:
      after: [quarto, lightbox]

强制让你的过滤器在所有其他内置/第三方过滤器之后运行。

5. 排查图书项目的特殊配置 #

• 检查图书的_quarto.yml中是否有site-url、base-url等配置，这类配置可能改变链接的生成逻辑；
• 测试最小化图书项目：创建仅包含2-3个页面的极简图书，排除其他复杂配置（如交叉引用、自定义模板）的干扰，验证过滤器是否能正常工作。

6. 确认链接的来源类型 #

区分链接是手动编写的还是Quarto自动生成的（如交叉引用、章节链接）：

• 手动编写的带.html的链接：你的AST过滤器应该能处理；
• 自动生成的内部链接：这类链接通常在后期生成，需要依赖PostProcess阶段处理。

内容的提问来源于stack exchange，提问作者Rafael Tavares Juliani