Marked.js 自定义代码块渲染器使用指南

概述

Marked.js 是一个流行的 Markdown 解析库，它允许开发者通过自定义渲染器来修改 Markdown 元素的渲染方式。本文将重点介绍如何在 Marked.js v13 版本中正确实现自定义代码块(code block)的渲染功能。

问题背景

在 Marked.js v13 版本中，许多开发者尝试自定义代码块渲染器时遇到了问题。即使完全复制了库内部的代码实现，仍然会出现渲染错误。这主要是因为 v13 版本引入了一个重要的渲染器架构变更，但为了保持向后兼容性，这个变更默认是关闭的。

解决方案

要正确实现自定义代码块渲染器，需要在调用 marked.use() 方法时设置 useNewRenderer: true 选项。这个选项告诉 Marked.js 使用新的渲染器架构来处理自定义渲染逻辑。

marked.use({
  useNewRenderer: true,
  renderer: {
    code({ text, lang, escaped }) {
      // 自定义渲染逻辑
    }
  }
});

技术细节

新旧渲染器架构差异

1. 旧版渲染器：接收的参数是简单的字符串和布尔值
2. 新版渲染器：接收一个包含完整 token 信息的对象参数

代码块渲染器实现要点

一个完整的自定义代码块渲染器应该处理以下关键点：

1. 语言标识处理：从 lang 参数中提取有效的语言标识
2. 代码内容处理：移除末尾多余的换行符并添加一个标准换行符
3. 转义处理：根据 escaped 参数决定是否需要对代码内容进行 HTML 转义
4. HTML 结构生成：构建包含正确 class 的 pre 和 code 标签

最佳实践

1. 版本兼容性：在 v13 中明确指定 useNewRenderer，在即将到来的 v14 中这将不再是必须的
2. 转义处理：重用 Marked.js 内部的 escape 函数确保一致性
3. HTML 安全：始终对用户提供的内容进行适当的转义处理
4. 测试覆盖：确保测试用例覆盖有语言标识和无语言标识两种情况

示例实现

const renderer = {
  code({ text, lang, escaped }) {
    const langString = (lang || '').match(/^\S*/)?.[0];
    const code = text.replace(/\n$/, '') + '\n';

    if (!langString) {
      return `<pre><code>${escaped ? code : escape(code, true)}</code></pre>\n`;
    }

    return `<pre><code class="language-${escape(langString)}">${
      escaped ? code : escape(code, true)
    }</code></pre>\n`;
  }
};

总结

Marked.js 提供了强大的自定义渲染能力，但在 v13 版本中需要注意启用新的渲染器架构。理解渲染器的参数结构和正确处理 HTML 转义是实现安全、稳定自定义渲染器的关键。随着 v14 版本的发布，这一过程将变得更加简单直观。