defuddle 脚注标准化实战:以 Google Docs ftnt/ftnt_ref 模式为例

原创2026-10-14 10:34:151,612 阅读
文章标签:后端

defuddle 脚注标准化实战:以 Google Docs ftnt/ftnt_ref 模式为例

导读

defuddle 是一个能够把任意网页正文提取为 Markdown 的开源库,其核心能力之一是把形态各异的 HTML 脚注统一成标准结构并输出为 Markdown 脚注语法。本文以仓库内置的测试用例 footnotes--google-docs-ftnt 为切入点,完整剖析 Google Docs/Sites 导出的 ftnt/ftnt_ref 脚注标记在 defuddle 中的识别、收集、去重与 Markdown 输出全过程。读完本文,你将理解 defuddle 的脚注处理管线如何运作、Google Docs 脚注模式的实现细节,以及如何利用 fixtures 测试体系验证这类提取行为。

一、什么是 Google Docs 的 ftnt/ftnt_ref 脚注模式

Google Docs 与 Google Sites 导出的 HTML 使用一套固定命名的 id 前缀来标记脚注,其结构清晰、高度可预测。仓库中对应的测试夹具 tests/fixtures/footnotes--google-docs-ftnt.html 在注释中明确记录了这套模式:

  • 正文内联引用:<sup id="ftnt_refN"><a href="#ftntN">[N]</a></sup>,即以 ftnt_ref 为前缀的 sup 元素包裹指向 #ftntN 的锚点;
  • 脚注定义:<p id="ftntN">,段落内包含返回引用 a[href="#ftnt_refN"];
  • 每个脚注定义通常被单独包裹在一个 <div> 中,前面还有一个 <h3>Footnotes</h3> 标题作为分隔。

夹具中的正文结构(摘录)如下:

<p>…which developed working exploits <span style="font-style: italic;">181</span>&nbsp;times,
   and achieved register control on 29 more.<sup id="ftnt_ref1"><a href="#ftnt1">[1]</a></sup></p>

<div>
  <p id="ftnt1"><a href="#ftnt_ref1">[1]</a>&nbsp;These exploits target a
    testing harness mimicking a content process, …</p>
</div>

这套命名与 Microsoft Word 导出的 _ftn/_ftnref 模式(见 src/elements/footnotes.ts 中的 tryWordExport)形成对照,是 defuddle 专门针对文档工具导出格式做的适配之一。

二、期望输出:从 HTML 到标准 Markdown 脚注

该用例的期望输出文件正是本文关联文档 tests/expected/footnotes--google-docs-ftnt.md。它由两部分组成:

  1. JSON 元数据前言(代码块形式),记录提取时的结构化信息:
{
  "title": "Google Docs footnotes: ftnt/ftnt_ref pattern",
  "author": "",
  "site": "google-docs-ftnt",
  "published": ""
}
  1. Markdown 正文,其中两个内联引用被转换为 Markdown 脚注语法,脚注定义收敛到文末:
These capabilities have emerged very quickly. Our internal evaluations showed that the model generally had a near-0% success rate at autonomous exploit development. But the new preview is in a different league. The previous model turned vulnerabilities into shell exploits only two times out of several hundred attempts. We re-ran this experiment as a benchmark for the preview, which developed working exploits 181 times, and achieved register control on 29 more.[^1]

Separately, we found that it could chain together multiple vulnerability classes to achieve full remote code execution in controlled test environments.[^2]

[^1]: These exploits target a testing harness mimicking a content process, without the browser's process sandbox or other defense-in-depth mitigations.

[^2]: This testing was conducted in isolated environments with no connection to production systems.

对比夹具 HTML 可以观察到几处关键清洗结果:内联 <span style="font-style: italic;"> 等样式包装被剥除、&nbsp; 被还原为普通空格、[1] 标记与返回链接被移除,最终只保留语义上干净的正文与脚注内容。脚注编号 [^1]、[^2] 与正文引用一一对应,构成完整可解析的 Markdown 文档。

三、源码实现:tryGoogleDocs 的识别与收集

Google Docs 模式的核心处理逻辑位于 src/elements/footnotes.ts 的 tryGoogleDocs 方法(第 485~525 行)。它作为 collectFootnotes 的兜底策略之一被调用,其执行流程如下:

  1. 按 id 前缀收集候选:element.querySelectorAll('p[id^="ftnt"]') 抓取所有以 ftnt 开头的段落,并通过正则 /^ftnt(\d+)$/ 校验 id 是否为纯数字后缀;
  2. 数量守卫:gdocPairs.length < 2 时直接返回。这是 defuddle 反误判设计的一部分——要求至少两条脚注互相印证,避免把正文中孤立的 ftnt* 段落误当作脚注;
  3. 编号排序:按数字升序排列,确保输出顺序稳定;
  4. 克隆并剥离返回链接:clone.querySelector('a[href*="#ftnt_ref"]')?.remove(),把 [1] 这样的返回引用从脚注内容中删除;
  5. 登记脚注:调用 addFootnote(state, originalId, contentDiv, num),其中 num 为显式编号。addFootnote 的实现(第 122~133 行)在传入 explicitNum 时以该数字作为脚注 key,并把计数推进到 explicitNum + 1,从而让后续按顺序收集的脚注不会与之冲突;
  6. 待清理列表:把脚注段落 p#ftntN 加入 pendingRemovals;若其父级是只有这一个子节点的 <div>,则连同该 div 一起移除(对应夹具中每个脚注外层包裹的 <div>);
  7. 移除 "Footnotes" 标题:检查第一个脚注之前的兄弟元素,若为 h1~h6 且文本匹配 FOOTNOTE_SECTION_RE(/^(foot\s*notes?|end\s*notes?|notes?|references?)$/i,见第 7 行),则一并移除。

这些待移除元素最终在 standardizeFootnotes 末尾统一从 DOM 中删除(第 1375~1376 行),保证原始页面结构不被残留的脚注容器污染。

值得注意的是 tryGoogleDocs 在兜底链中的位置(第 313~322 行):

tryDataTypeFootnotes → tryGenericIdDetection → tryWordExport → tryGoogleDocs
→ tryLabeledSection → tryLooseFootnotes → tryClassFootnote → tryBrSeparatedFootnotes

整个兜底链受 if (state.count > 1) break; 门控——一旦已有脚注被收集,后续策略不再执行。这保证了不同来源的识别策略互不干扰。

四、内联引用匹配与标准化输出

4.1 内联引用选择器

正文中的 sup<a href="https://link.gitcode.com/i/2251c37de79bdddccb3929b8aed440ac" target="_blank">id="ftnt_refN"] 由 [src/constants.ts 中导出的 FOOTNOTE_INLINE_REFERENCES 捕获,其中专门有一项:

'sup[id^="ftnt_ref"] a[href^="#ftnt"]', // Google Docs/Sites

当 standardizeFootnotes(第 1219 行起)遍历这些内联引用时,先通过 INLINE_REF_EXTRACTORS 表提取脚注 id;对 Google Docs 场景,该表没有专属规则,于是走到兜底分支(第 1274~1278 行):直接用 a[href="#ftnt1"] 的 href 片段作为 footnoteId = "ftnt1",再通过 footnotesByOriginalId 映射表找到对应的标准化编号。

随后 findOuterFootnoteContainer 向上回溯包裹 sup/span,并用 createFootnoteReference 生成标准引用:<sup id="fnref:1"><a href="#fn:1">1</a></sup>。由于外层 sup 与内层锚点同时匹配,supGroups 去重逻辑(第 1290~1292 行)确保同一脚注只生成一个引用。

4.2 统一的标准 HTML 结构

README 的 "Footnotes" 一节(README.md)给出了 defuddle 的标准脚注 HTML 形态:

Inline reference<sup id="fnref:1"><a href="#fn:1">1</a></sup>.

<div id="footnotes">
  <ol>
    <li class="footnote" id="fn:1">
      <p>
        Footnote content.&nbsp;<a href="#fnref:1" class="footnote-backref">↩</a>
      </p>
    </li>
  </ol>
</div>

standardizeFootnotes 末尾(第 1366~1383 行)会构造 #footnotes 容器:每个脚注经 createFootnoteItem 生成 li.footnote,其 id 为 fn:N,最后一个段落末尾追加 ↩ 返回链接(a.footnote-backref,指向 #fnref:N);仅当列表非空时才追加到内容元素末尾。

4.3 渲染为 Markdown 脚注

脚注的 Markdown 渲染由 src/markdown.ts 的两个 turndown 规则完成:

  • citations 规则匹配 sup[id^="fnref:"],解析出 fnref: 后的编号,输出 [^N] 形式的内联引用;
  • footnotesList 规则匹配 #footnotes 容器内的 <ol>,逐条读取 li 的 id(剥离 fn: 前缀),删除开头与编号同文的 <sup> 标记,并用正则 /\s*↩︎$/ 去掉内容末尾的返回箭头,最终生成 [^N]: 内容 的定义行。

此外,src/markdown.ts 的 formatFootnoteId 会对脚注 id 做小写化与百分号编码(非 [a-z0-9_-] 字符转为 %xxxx),保证含引号、冒号等特殊字符的脚注 id 也能安全进入 Markdown 文本。

五、管线位置:standardize 选项与执行顺序

脚注标准化是 defuddle 内容清洗管线中的一个显式步骤。src/defuddle.ts 中,在内容元素确定之后依次执行:

// Pull in footnote sections that live outside the main content element
if (options.standardize) {
    this.adoptExternalFootnotes(mainContent!, clone);
}

// Standardize footnotes before cleanup (CSS sidenotes use display:none)
if (options.standardize) {
    standardizeFootnotes(mainContent!);
    standardizeCallouts(mainContent!);
}

两点值得注意:

  • 整个过程由 standardize 选项控制,该选项默认值为 true(见 README.md 的选项表);
  • adoptExternalFootnotes 会先把位于主内容元素之外(例如页面尾部独立容器)的脚注定义并入主内容,再交给 standardizeFootnotes 统一处理,这保证即使脚注列表与正文分离也能正确关联。

六、测试验证体系:fixtures 与期望输出

footnotes--google-docs-ftnt 用例隶属于 defuddle 的 fixtures 测试体系,其机制记录在 tests/fixtures.test.ts 中:

  1. 自动扫描 tests/fixtures/ 下所有 .html 文件;
  2. 用 defuddle 处理每个夹具,得到 Markdown 结果;
  3. 与 tests/expected/ 中同名的 .md 期望文件比对,期望文件头部是 JSON 元数据代码块、正文是 Markdown 内容;
  4. 若期望文件不存在则生成基线;若结果与期望不一致则测试失败。

配套的 tests/helpers.ts 提供了两种归一化工具:normalizeHtmlAttributes 排序属性顺序以消除不同 DOM 实现的差异,normalizeMarkdownHtml 在解析 Markdown 时保留代码块内的字节内容。因此即使 DOM 实现(jsdom / linkedom,通过 DOM 环境变量切换)不同,脚注提取结果的断言依然稳定。

对于本文讨论的场景,验证链条可以概括为:

tests/fixtures/footnotes--google-docs-ftnt.html
        ↓ defuddle 管线(standardizeFootnotes + Markdown 渲染)
tests/expected/footnotes--google-docs-ftnt.md(期望输出)

七、边界与注意事项

从实现代码可以总结出 Google Docs 脚注模式处理的几个约束,帮助你在使用或扩展时规避误判:

  • 最少两条脚注:tryGoogleDocs 要求至少两个 p[id^="ftnt"] 段落才会启用,单条孤立脚注不会被识别(这正是防止正文中偶然出现的 ftnt* id 被误清理的保护);
  • 严格数字后缀:id 必须匹配 /^ftnt(\d+)$/,带字母或符号后缀的变体不在该策略处理范围内;
  • 返回链接定向剥离:只移除 a[href*="#ftnt_ref"],脚注内容中的其他链接不受影响;
  • 外层包裹结构:仅当脚注段落的父级 <div> 恰好只有一个子节点时才移除该 div,避免误删包含其他内容的容器;
  • 编号顺序保持:通过显式编号 addFootnote 保留原始 ftntN 的序号,使 Markdown 输出编号与原文档一致。

结语

通过 footnotes--google-docs-ftnt 这一用例,可以完整看到 defuddle 处理脚注的"三幕剧":先是 tryGoogleDocs 用 id 前缀与数量守卫识别并收集定义,再由 standardizeFootnotes 把内联引用和定义统一成 #footnotes + fn:N 标准结构,最后经 markdown 渲染规则输出为 [^N] 与 [^N]: 的标准 Markdown 脚注。整套逻辑以 fixtures 测试闭环保障,既有面向真实站点形态的鲁棒适配,又有可复现、可回归的验证手段。若你需要在类似场景中处理 Google Docs 导出的内容,这套"识别 → 标准化 → 渲染 → 测试"的路径可以直接借鉴。

登录后查看全文
defuddle