Marked.js 中自定义标题渲染器的正确实现方式

在使用 Marked.js 这个流行的 Markdown 解析库时，开发者经常需要自定义渲染器来实现特定的输出格式。本文将通过一个实际案例，讲解如何正确实现标题(heading)的自定义渲染。

问题背景

在 Marked.js 中，标题(heading)是一种块级(block)标记，而标题内部的文本则可能包含强调(strong)等行内(inline)标记。当开发者尝试自定义标题渲染器时，可能会遇到"Token with 'strong' type was not found"这样的错误。

错误示例分析

考虑以下代码，开发者希望将标题渲染为加粗文本：

import { type RendererObject, type Tokens, marked } from "marked";

const customRenderer: RendererObject = {
    heading(tokens: Tokens.Heading): string {
        const text = this.parser.parse(tokens.tokens);
        return `*${text.trim()}*\n`;
    },
};

这段代码会抛出错误，因为错误地使用了parse方法来处理标题内部的标记。

根本原因

Marked.js 的标记分为两大类：

1. 块级标记(Block tokens)：如标题(heading)、段落(paragraph)等
2. 行内标记(Inline tokens)：如强调(strong)、斜体(em)等

标题(heading)是一个块级标记，但其内容(tokens.tokens)包含的是行内标记。使用parse方法期望处理块级标记，而实际上需要处理的是行内标记。

正确解决方案

正确的做法是使用parseInline方法来处理标题内部的标记：

const customRenderer: RendererObject = {
    heading(tokens: Tokens.Heading): string {
        const text = this.parser.parseInline(tokens.tokens);
        return `*${text.trim()}*\n`;
    },
};

技术要点总结

1. 标记类型区分：理解块级标记和行内标记的区别是使用 Marked.js 的关键
2. 解析方法选择：
   • parse方法用于处理块级标记
   • parseInline方法用于处理行内标记
3. 标题的特殊性：标题虽然是块级标记，但其内容由行内标记组成

最佳实践建议

1. 在自定义渲染器时，先确定要处理的标记类型
2. 对于包含内容的块级标记(如标题)，注意其内容可能是行内标记
3. 当遇到标记类型不匹配的错误时，检查是否使用了正确的解析方法

通过理解这些概念，开发者可以更灵活地使用 Marked.js 实现各种自定义渲染需求。