Turndown项目中使用自定义规则保留HTML标签的方法

概述

在使用Turndown这个HTML转Markdown的库时，开发者有时会遇到需要保留特定HTML标签不被转义的情况。本文将详细介绍如何通过自定义规则来实现这一需求。

问题背景

在将HTML转换为Markdown的过程中，Turndown默认会将HTML标签转义为字符实体（如将<转换为<）。但在某些场景下，我们可能希望在生成的Markdown中保留某些HTML标签的原始形式。

解决方案

Turndown提供了强大的自定义规则功能，允许开发者针对特定HTML元素创建专门的转换逻辑。以下是实现保留HTML标签的具体方法：

1. 创建自定义规则

通过addRule方法可以添加自定义转换规则。每个规则需要定义两个关键部分：

• filter函数：用于匹配需要应用此规则的HTML元素
• replacement函数：定义如何将匹配的元素转换为Markdown

2. 实现保留HTML标签

在replacement函数中，可以直接返回包含HTML标签的字符串。Turndown不会对这些在规则中明确返回的HTML标签进行转义处理。

示例代码

以下是一个完整的示例，展示如何保留<Icon>标签：

const TurndownService = require('turndown');
const turndownService = new TurndownService();

turndownService.addRule('external-link', {
    filter: function (node) {
        const aclass = node.getAttribute("class");
        return node.nodeName === 'A' && aclass === 'LinkOut';
    },
    replacement: function (content, node) {
        let url = node.getAttribute("href");
        if (!url?.startsWith('http')) {
            return content;
        }
        return `[${content} <Icon icon="fa-external-link" size="sm" />](${url})`;
    },
});

const htmlStr = `<a href='https://www.google.com' class='LinkOut'>Go to Google</a>`;
console.log(turndownService.turndown(htmlStr));

执行上述代码将输出：

[Go to Google <Icon icon="fa-external-link" size="sm" />](https://www.google.com)

注意事项

1. 标签匹配：确保filter函数能够准确匹配到目标元素，避免规则应用到不需要的元素上。

2. URL验证：如示例所示，建议对链接进行验证（如检查是否以'http'开头），以确保只转换符合条件的链接。

3. 自定义标签：Turndown不会对自定义标签（如<Icon>）进行特殊处理，因此可以直接在输出字符串中包含这些标签。

4. Markdown兼容性：虽然可以在Markdown中嵌入HTML，但要注意目标渲染器是否支持这些HTML标签。

进阶用法

对于更复杂的需求，可以在replacement函数中实现更精细的控制：

• 根据元素属性动态生成不同的HTML标签
• 组合多个HTML标签
• 添加条件逻辑来决定是否包含特定标签

总结

通过Turndown的自定义规则功能，开发者可以灵活控制HTML到Markdown的转换过程，包括保留特定的HTML标签。这种方法既保持了Markdown的简洁性，又能在需要时嵌入HTML以实现更丰富的展示效果。