【免费下载】 Marked.js 高级扩展指南：自定义渲染器与解析器

什么是 Marked.js 扩展

Marked.js 是一个高效的 Markdown 解析器，其设计遵循单一职责和开闭原则，使得开发者能够轻松扩展其功能。通过扩展机制，你可以自定义 Markdown 的解析和渲染行为，实现特殊语法支持或修改默认输出格式。

扩展基础：marked.use() 方法

marked.use() 是扩展 Marked.js 的核心方法，它接受一个包含配置选项的对象：

import { marked } from 'marked';

marked.use({
  // 基础选项
  pedantic: false,
  gfm: true,
  breaks: false,
  
  // 扩展点
  renderer: { /* 自定义渲染器 */ },
  tokenizer: { /* 自定义解析器 */ },
  walkTokens: (token) => { /* 令牌处理函数 */ },
  extensions: [ /* 自定义扩展 */ ]
});

多扩展合并

可以一次性应用多个扩展配置，它们会按顺序合并：

marked.use(extension1, extension2, extension3);

注意：renderer、tokenizer、hooks、walkTokens 和 extensions 会被合并而非覆盖。

Marked.js 解析流程解析

理解 Marked.js 的工作流程对开发扩展至关重要：

1. 词法分析(Lexer)：将输入字符串分解为令牌(token)
2. 令牌生成(Tokenizer)：识别特定语法模式并生成令牌对象
3. 令牌遍历(WalkTokens)：后处理令牌树
4. 语法分析(Parser)：将令牌树转换为HTML
5. 渲染(Renderer)：生成最终的HTML输出

自定义渲染器(Renderer)

渲染器负责将令牌转换为HTML。通过覆盖默认渲染方法，你可以完全控制输出格式。

渲染器示例：增强标题

const renderer = {
  heading({ text, depth }) {
    const escapedText = text.toLowerCase().replace(/[^\w]+/g, '-');
    return `
      <h${depth}>
        <a name="${escapedText}" class="anchor" href="#${escapedText}">
          <span class="header-link"></span>
        </a>
        ${text}
      </h${depth}>`;
  }
};

marked.use({ renderer });

可用渲染方法

块级元素渲染

• code(): 代码块
• blockquote(): 引用块
• heading(): 标题
• list(): 列表
• table(): 表格等

行内元素渲染

• strong(): 加粗文本
• em(): 斜体文本
• link(): 超链接
• image(): 图片等

自定义解析器(Tokenizer)

解析器负责识别Markdown语法并生成令牌对象。

解析器示例：支持LaTeX代码

const tokenizer = {
  codespan(src) {
    const match = src.match(/^\$+([^\$\n]+?)\$+/);
    if (match) {
      return {
        type: 'codespan',
        raw: match[0],
        text: match[1].trim()
      };
    }
    return false; // 回退到默认解析
  }
};

marked.use({ tokenizer });

可用解析方法

块级解析

• heading(): 标题识别
• code(): 代码块识别
• table(): 表格识别等

行内解析

• codespan(): 行内代码
• link(): 链接识别
• emStrong(): 强调文本识别等

令牌遍历(WalkTokens)

walkTokens 函数允许你在渲染前修改令牌树：

marked.use({
  walkTokens(token) {
    if (token.type === 'heading') {
      token.depth += 1; // 将所有标题级别降低一级
    }
  }
});

钩子函数(Hooks)

钩子提供更灵活的扩展点：

• preprocess: 预处理原始Markdown
• postprocess: 后处理生成的HTML
• processAllTokens: 处理所有令牌

钩子示例：Front Matter支持

import fm from 'front-matter';

marked.use({
  hooks: {
    preprocess(markdown) {
      const { attributes, body } = fm(markdown);
      // 将front matter属性应用到配置
      Object.assign(this.options, attributes);
      return body;
    }
  }
});

自定义扩展(Extensions)

对于全新的语法支持，可以创建完整扩展：

marked.use({
  extensions: [{
    name: 'underline',
    level: 'inline',
    start(src) { return src.indexOf('++'); },
    tokenizer(src) {
      const match = src.match(/^\+\+(.+?)\+\+/);
      if (match) {
        return {
          type: 'underline',
          raw: match[0],
          text: match[1]
        };
      }
    },
    renderer(token) {
      return `<u>${token.text}</u>`;
    }
  }]
});

扩展关键属性

1. name: 扩展标识符
2. level: 块级(block)或行内(inline)
3. start: 检测潜在令牌起始位置
4. tokenizer: 生成令牌对象
5. renderer: 渲染令牌为HTML

最佳实践建议

1. 避免重复注册：扩展应只注册一次，通常在模块全局作用域
2. 合理使用回退：返回false可回退到前一个处理程序
3. 考虑性能：正则表达式应尽量高效
4. 保持兼容：修改默认行为时考虑对现有文档的影响

通过灵活运用这些扩展机制，你可以让 Marked.js 完美适应各种特殊需求，从简单的格式调整到复杂的新语法支持都不在话下。