Quarto Book章节标题加脚注：PDF正常HTML异常如何解决？

问题根源 #

Quarto Book的HTML渲染机制会将章节标题同步到目录和首页（index.qmd），导致标题内的脚注被重复解析，进而生成多个脚注副本、出现在错误页面，还会被纳入目录标题中。

兼容实现方法 #

方法1：HTML注释隔离目录脚注（轻量方案） #

在章节标题中用HTML注释包裹一份脚注，正文标题保留正常脚注格式。HTML渲染时目录会忽略注释内容，正文标题的脚注正常显示；PDF渲染不受注释影响，可直接解析所有内容。示例：

# 章节标题 <!-- ^[脚注内容] -->^[脚注内容]

方法2：JS脚本清理重复脚注（通用方案） #

在_quarto.yml中为HTML格式添加后置脚本，渲染完成后自动清理目录中的脚注引用和重复的脚注条目：

format:
  html:
    include-after-body: |
      <script>
        // 移除目录中的脚注引用
        document.querySelectorAll('.toc-item .footnote-ref').forEach(el => el.remove());
        // 删除重复的脚注条目
        const footNoteMap = new Map();
        document.querySelectorAll('.footnote-item').forEach(item => {
          const itemId = item.id;
          if (footNoteMap.has(itemId)) {
            item.remove();
          } else {
            footNoteMap.set(itemId, true);
          }
        });
      </script>
  pdf:
    keep-tex: true # 保持PDF渲染逻辑不变

方法3：正文定义脚注（推荐方案） #

将脚注定义从标题移到章节正文开头，避免标题脚注被多位置解析。同时开启交叉引用配置确保渲染正常：

# 章节标题 [^note1]

[^note1]: 脚注内容，放在章节正文最上方

_quarto.yml中添加交叉引用配置：

crossref:
  footnotes: true

验证最小示例 #

以方法1为例，创建测试项目：

1. _quarto.yml配置：

project:
  type: book

book:
  title: "测试书籍"
  chapters:
    - index.qmd
    - chapter1.qmd

format:
  html:
    toc: true
  pdf:
    toc: true

2. chapter1.qmd内容：

# 第一章：测试标题 <!-- ^[这是章节脚注] -->^[这是章节脚注]

正文内容...

渲染后HTML目录无脚注、正文脚注正常显示，PDF也能正确渲染脚注。

内容的提问来源于stack exchange，提问作者John K. Kruschke