Turndown 终极指南：掌握 addRule、keep、remove 三大核心 API
项目地址: https://gitcode.com/gh_mirrors/tu/turndown Turndown 是一个强大的 JavaScript HTML 到 Markdown 转换库，它能够将复杂的 HTML 文档优雅地转换为简洁的 Markdown 格式。对于需要处理网页内容、博客文章或文档转换的开发者和内容创作者来说，这是一个不可或缺的工具。🛠️
为什么需要 Turndown 转换器？
在现代 Web 开发中，我们经常需要在不同格式之间转换内容。HTML 到 Markdown 的转换尤其重要，因为 Markdown 已成为文档编写、博客发布和技术写作的标准格式。Turndown 提供了简单而强大的 API，让您能够精确控制转换过程。
addRule 方法：自定义转换规则
addRule 是 Turndown 最强大的功能之一，它允许您为特定的 HTML 元素定义自定义的 Markdown 转换规则。通过 src/turndown.js 中的实现，您可以为任何 HTML 标签创建个性化的转换逻辑。
addRule 的核心参数
- key: 规则的唯一标识符，便于后续引用和管理
- rule: 包含
filter和replacement函数的配置对象
实际应用示例
假设您需要将 <strike> 标签转换为 Markdown 的删除线语法：
turndownService.addRule('strikethrough', {
filter: ['del', 's', 'strike'],
replacement: function (content) {
return '~~' + content + '~~'
}
})
这个简单的规则就能让所有删除线元素正确转换为 Markdown 格式！
keep 方法：保留原始 HTML
有时候，您可能希望某些 HTML 元素在转换过程中保持原样，不被转换为 Markdown。keep 方法就是为此设计的。🎯
keep 的典型使用场景
- 保留
<del>和<ins>标签用于版本控制 - 保持特定的样式或布局元素不变
- 确保重要的 HTML 结构不被破坏
配置示例
// 保留删除线和插入标签
turndownService.keep(['del', 'ins'])
通过 src/rules.js 可以看到，keep 规则会优先于其他规则执行。
remove 方法：完全移除元素
在某些情况下，您可能希望完全删除某些 HTML 元素及其内容。remove 方法提供了这种能力，让您可以清理不需要的内容。
remove 的实际应用
- 移除广告或无关的页面元素
- 清理样式标签和脚本内容
- 过滤掉特定的导航或页脚信息
使用示例
// 移除所有删除线元素
turndownService.remove('del')
规则优先级：理解执行顺序
Turndown 按照特定的顺序应用规则，了解这个顺序对于正确配置转换器至关重要：
- 空白规则：处理只包含空白的元素
- 自定义规则：通过
addRule添加的规则 - CommonMark 规则：标准的 Markdown 转换规则
- keep 规则：保留为 HTML 的元素
- remove 规则：完全移除的元素
- 默认规则：处理其他所有情况的回退规则
高级配置技巧
组合使用多个方法
Turndown 支持方法链式调用，让您可以流畅地配置转换器：
var turndownService = new TurndownService()
.addRule('strikethrough', {
filter: ['del', 's', 'strike'],
replacement: function (content) {
return '~~' + content + '~~'
}
})
.keep(['ins'])
.remove(['script'])
常见问题解答
Q: 如何处理复杂的嵌套结构？
A: Turndown 会自动处理嵌套的 HTML 元素，您只需要关注单个元素的转换规则即可。
Q: 性能如何？
A: Turndown 经过优化，能够高效处理大型 HTML 文档。
Q: 是否支持插件？
A: 是的，Turndown 支持插件系统，可以轻松扩展功能。
总结
掌握 Turndown 的 addRule、keep 和 remove 三大核心 API，您就掌握了 HTML 到 Markdown 转换的精髓。无论您是构建内容管理系统、开发博客平台，还是进行文档处理，这些方法都能为您提供强大的控制能力。
通过 src/commonmark-rules.js 您可以深入了解默认的转换规则，为自定义配置提供参考。开始使用 Turndown，让 HTML 到 Markdown 的转换变得简单而高效！✨
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
