★ FEATURED ARTICLE 后端【免费下载链接】defuddleGet the main content of any page as Markdown.项目地址https://gitcode.com/gh_mirrors/de/defuddle点击查看免费下载导读在 HTML 早期的网站中用table做页面布局table-based layout是极为常见的做法——整页内容被塞进一层层嵌套的表格单元格里。defuddle一个将任意网页正文提取为 Markdown的库需要在这种结构中准确区分承载数据的表格与仅用于定位/排版的布局表格并把后者安全地解包为普通文本流。本文以仓库测试用例table-layout--single-column单列布局表格为主线结合源码实现与同系列测试夹具讲清楚 defuddle 是如何识别、解包布局表格并输出干净 Markdown 的。一、场景还原单列布局表格到底长什么样测试夹具 tests/fixtures/table-layout--single-column.html 是一个典型的整页用表格框起来的旧式页面一个idlayout的表格其中只有一个单元格width70%、vertical-align: top所有正文内容标题、段落、列表都堆在这个单元格里body table idlayout tr td width70% stylevertical-align: top; h1Welcome/h1 pHello, welcome to my website!/p h2Projects/h2 ul lia hrefhttps://example.com/project-oneProject One/a - a cool project/li lia hrefhttps://example.com/project-twoProject Two/a - another project/li lia href/local-page.htmlLocal Page/a/li /ul h2Contact/h2 pFind me on a hrefhttps://example.com/socialsocial media/a or email stronghello at example.com/strong./p /td /tr /table /body /html这类表格没有任何数据语义没有th表头、没有多列数据、单元格本身只承担把内容居中/定宽的排版职责。若直接按数据表格方式转 Markdown会产出一堆毫无意义的管道符语法| --- |和多余表格结构严重污染正文。二、期望输出defuddle 给出的标准答案同名的期望文件 tests/expected/table-layout--single-column.md 记录了 defuddle 提取该页面的标准结果。文件由两部分组成JSON 元数据前导Markdown 正文。{ title: My Homepage, author: , site: table-layout--single-column, published: }## Welcome Hello, welcome to my website! ## Projects - [Project One](https://example.com/project-one) - a cool project - [Project Two](https://example.com/project-two) - another project - [Local Page](https://table-layout--single-column/local-page.html) ## Contact Find me on [social media](https://example.com/social) or email **hello at example.com**.对比可见 defuddle 完成了三件事布局表格被完全解包整个tabletrtd结构消失单元格内的内容直接提升为文档级内容标题层级被标准化原页面h1Welcome在正文中变为h2——这是 defuddle 的标题标准化逻辑见standardizeContent中standardizeHeadings将 H1 让位给文章标题后的结果页面title中的 My Homepage 被提取为元数据title内容结构原样保留段落、无序列表、链接、加粗等 Markdown 语义全部无损继承相对链接被解析为绝对链接原/local-page.html依据站点 URL 被解析为https://table-layout--single-column/local-page.html。需要说明的是元数据前导是测试套件为了可对比、可评审而附加的格式详见下文测试机制生产环境直接调用Defuddle时正文内容即contentMarkdown字段。三、源码级原理两处布局表格处理逻辑defuddle 对布局表格的处理不是单一逻辑而是在DOM 标准化阶段与Markdown 序列化阶段各有一道防线二者共同保证提取结果干净可靠。3.1 DOM 标准化阶段standardizeElements解包单列表格src/standardize.ts 中的standardizeElements对残留的布局表格做了解包处理第 1471–1500 行。核心逻辑如下// Unwrap single-column layout tables (used for styling/positioning, not data) const directCells Array.from(table.querySelectorAll(td, th)) .filter(cell isDirectTableChild(cell, table)); // Skip data tables that have direct header cells if (directCells.some(cell cell.tagName TH)) return; const directRows Array.from(table.querySelectorAll(tr)) .filter(row isDirectTableChild(row, table)); if (directRows.length 0) return; // Check that every row has at most one direct cell const isSingleColumn directRows.every(tr directCells.filter(cell cell.parentNode tr).length 1 ); if (!isSingleColumn) return; const fragment doc.createDocumentFragment(); directCells.forEach(cell { while (cell.firstChild) { fragment.appendChild(cell.firstChild); } }); table.replaceWith(fragment);关键判定要点只统计直接子单元格借助 src/utils/dom.ts 的isDirectTableChild向上回溯父链若中途遇到任何TABLE节点则判定为不属于外层表格的直接子级从而排除嵌套表格干扰跳过数据表只要表格的直接子单元格中出现th表头就视为数据表格不做解包单列判定每一行至多只有一个直接单元格才认定是单列布局表解包方式把每个单元格的firstChild依次移入DocumentFragment再用该片段替换整个table单元格内的块级内容自然上浮为正文。这一层逻辑与unwrapLayoutTablessrc/standardize.ts相互配合后者处理选择器移除后只剩一个非空单元格、且该单元格内恰好包着一个块级元素的布局表场景例如 TOC 单元格被清空后的残留壳。3.2 Markdown 序列化阶段turndown 的 table 规则兜底标准化阶段处理过的文档最终交给 turndown 序列化为 Markdown。在 src/markdown.ts 的自定义table规则中存在与 DOM 阶段同构但独立的布局表检测turndownService.addRule(table, { filter: table, replacement: function(content, node) { // 1. 方程表格ArXiv/Wikipedia 的 ltx_equation 等走专用处理 // 2. 检测布局表含嵌套表或直接单元格数 1 const hasNestedTables Array.from(node.querySelectorAll(table)).some((t) t ! node); const directCells Array.from(node.querySelectorAll(td, th)).filter( (el) isDirectTableChild(el, node) ); if (hasNestedTables || directCells.length 1) { // 再判定是否严格单列 const isSingleColumn directRows.length 0 new Set(cellCounts).size 1 cellCounts[0] 1; // 布局表把各单元格内容扁平化后再递归序列化 if (isSingleColumn || hasNestedTables) { return \n\n turndownService.turndown( directCells.map((cell) serializeHTML(cell)).join() ) \n\n; } } // 3. 含 colspan/rowspan 的复杂表走 cleanupTableHTML // 4. 简单数据表按行列生成管道语法表格并统一补齐列宽 ... } });这段逻辑有几点值得注意嵌套表 布局表真实数据表不会在单元格里再嵌一个数据表所以存在嵌套表被直接视为布局特征。解包后内层的数据表格会各自独立渲染成自己的 Markdown 表格——这正是修复 issue #300嵌套布局表格的做法扁平化再序列化不是直接丢content而是把各直接单元格的 HTML 拼起来重新走一遍 turndown保证解包后的内容仍然经过完整的 Markdown 转换管线多列布局单元格按从左到右顺序读取注释明确说明 Multi-column layout cells read left-to-right确保多栏页面的阅读顺序正确兜底价值即便 DOM 标准化阶段因某些原因漏掉了布局表例如表格结构在序列化阶段仍带有多行turndown 规则仍会做二次判定避免输出破碎的管道符表格。3.3 空表格清理在标准化阶段还有一道前置清理src/standardize.ts所有单元格都没有文本、且不含图片/视频/音频/iframe/svg/math 的表格直接移除。这处理的是布局壳里只剩空白单元格的极端情况防止空表格残留在最终 Markdown 中。四、测试机制fixture 驱动的回归保障table-layout--single-column这个名称源自测试套件的自动发现机制。整个流程由 tests/fixtures.test.ts 驱动自动发现通过getFixtures()tests/helpers.ts扫描tests/fixtures/下所有.html文件文件名即测试名离线提取用Defuddle(doc, url, { separateMarkdown: true, fetch: offlineFetch })处理每个夹具——offlineFetch强制走确定性 DOM 提取路径避免网络请求导致测试不稳定对比或建基线createComparableResult把title/author/site/published四项元数据序列化为 JSON 代码块前导与contentMarkdown拼接后同tests/expected/下同名.md文件逐字节比对经normalizeMarkdownHtml归一化若期望文件不存在则自动生成基线输出完整性校验断言response.content与contentMarkdown均非空。这也是期望文件为何带有 JSON 前导的原因——它是测试可比对性的组成部分而不是最终给终端用户的产品格式。此外 tests/fixture-comparison.test.ts 保证了比对本身的公平性normalizeMarkdownHtml会把正文中嵌入的 SVG 等 HTML 做属性排序归一化但绝不解析 Markdown 代码围栏fence内的内容确保代码示例逐字节保留。五、同系列夹具单列、多列与周边表格的完整图景table-layout--前缀下还有三个夹具共同勾勒出 defuddle 对不同布局表格的完整处理策略5.1 双栏博客布局侧边栏被剥离tests/fixtures/table-layout--blogger-two-column.html 是经典的 Blogger 双栏布局外层表格左列放文章正文右列width150带左边框放友链、RSS、归档等侧边栏内容。期望输出 tests/expected/table-layout--blogger-two-column.md 中侧边栏链接全部消失只保留主列的文章正文、引言、注释与评论链接。这说明多列布局表格不会被整体解包为普通文本而是通过选择器/评分机制将侧边栏列作为非正文内容剔除主列内容再按正文提取。同时注意该期望输出中published被正确解析为2004-05-27T00:00:0000:00——页面里的日期文本被元数据提取器识别成了发布日期。5.2 经典文章页面布局表内的长文提取tests/fixtures/table-layout--paulgraham.com-makersschedule.html 对应的期望输出 tests/expected/table-layout--paulgraham.com-makersschedule.md 是一篇完整长文。它在表格布局的躯壳下包含标题、引言、多段落正文、加粗强调、超链接、脚注式致谢等复杂结构全部被无损提取为结构化 Markdown——这验证了布局表解包逻辑在真实世界长文页面上的可靠性。5.3 周边表格数据表被保留为 Markdown 表格tests/fixtures/table-layout--peripheral-tables.html 则展示了非布局表的一面摘要框单格带背景色的表格被当作普通块内容保留、目录TOC表格被内容清理移除、正文中的图片说明两列表格被保留为真实 Markdown 表格期望输出第 80–81 行的| ![Diagram...] | Phase G1... |管道语法。这说明 defuddle 并不会一刀切地删除所有表格而是严格区分布局用途与数据用途。六、在项目中使用与验证若想在本地复现本文所述行为可按以下方式操作# 安装依赖项目为 npm TypeScript见 package.json npm install # 运行全部测试含 fixtures 对比测试 npm test # 仅运行 fixtures 测试 npx vitest run tests/fixtures.test.ts若要新增一个布局表格场景夹具流程为把页面 HTML 放入tests/fixtures/首次运行npm test会自动生成tests/expected/下的基线期望文件人工评审基线内容无误后后续任何改动若导致提取结果偏离基线测试都会失败从而形成回归保护。若期望输出需要更新删除对应期望文件后重新运行测试即可。小结从table-layout--single-column这个最小的单列表格用例出发可以看到 defuddle 对表格布局页面形成了完整的三层防御体系预处理空表格直接移除src/standardize.tsDOM 标准化单列布局表解包、unwrapLayoutTables清理残留壳src/standardize.ts、src/standardize.ts序列化兜底turndown 的table规则二次检测嵌套表/单列表并扁平化src/markdown.ts。三者配合isDirectTableChildsrc/utils/dom.ts的直接子级判定在保留真实数据表含复杂表结构如colspan/rowspan走cleanupTableHTML以 HTML 形式保留的同时把旧时代遗留的表格布局彻底抹平最终交给用户的是一份语义清晰、可读性强的 Markdown 正文。这一处理能力正是 defuddle 面对海量历史网页博客平台、百科页面、个人主页仍能稳定输出干净正文的关键基础之一。赞分享后端【免费下载链接】defuddleGet the main content of any page as Markdown.项目地址https://gitcode.com/gh_mirrors/de/defuddle点击查看免费下载相关推荐从 HTML 表格到 Markdown 表格defuddle 复杂表格提取原理与 Fixture 验证实战从 HTML 表格到 Markdown 表格defuddle 复杂表格提取原理与 Fixture 验证实战 defuddle 是一款将任意网页正文提取为 Ma后端defuddle 表格布局检测如何从 Blogger 双栏页面中精准提取正文 Markdowndefuddle 表格布局检测如何从 Blogger 双栏页面中精准提取正文 Markdown 导读 本文围绕 defuddle 开源项目中的 table l后端Kimi-K3量化技术详解MXFP4权重压缩如何平衡性能与硬件需求Kimi K3量化技术详解MXFP4权重压缩如何平衡性能与硬件需求 在人工智能大模型快速发展的今天模型性能与硬件资源的矛盾日益突出。Kimi K3作为一款先上一篇Watermill中的消息流处理安全审计访问日志分析下一篇终极Conda包下载速度优化指南多线程与断点续传加速技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
