tech

Hexo 博客系统的 Mermaid 插件：hexo-markdown-mermaid

背景

最近 AI 生成文字时配合 Mermaid 绘制图表非常方便，想让博客支持 Mermaid 渲染。

调研发现现有方案 hexo-filter-mermaid-diagrams 已停止维护，无法兼容新版 Hexo。

解决方案：hexo-markdown-mermaid

我开发了一个轻量级的 Hexo 插件 hexo-markdown-mermaid，采用浏览器端渲染，零依赖，即装即用。

核心特点

  1. 零依赖 - 无需 Puppeteer，仅通过 CDN 引入 Mermaid.js
  2. 轻量级 - 核心代码仅约 20 行
  3. 配置灵活 - 支持自定义 Mermaid 版本和配置参数

工作原理

插件通过 Hexo 的 injector 在页面底部注入 Mermaid.js 和初始化代码：

1
2
3
4
5
6
hexo.extend.injector.register('body_end', `
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({startOnLoad: true});
</script>
`, 'default');

Mermaid 默认使用 .mermaid 选择器查找图表元素，而 Hexo 默认输出格式为 <pre class="mermaid">，因此无需额外配置即可自动渲染。

与语法高亮的兼容

如果使用 highlight.js，需要在 _config.yml 中排除 mermaid 语言：

1
2
3
highlight:
  exclude_languages:
    - mermaid

原因：highlight.js 会预编译代码块为 HTML，生成 <pre><code class="highlight mermaid">，而 Mermaid 默认查找 <pre class="mermaid">。通过排除让 highlight.js 跳过 mermaid 块，保留原始格式供 Mermaid 渲染。

实现细节

最初考虑过预编译方案（mermaid-cli），但依赖 Puppeteer 较重，不适合简单需求。

最终采用浏览器端渲染，通过 CDN 引入 Mermaid.js，配合 hexo.extend.injector 注入页面。

关键点：

  1. 使用 hexo.config.mermaid 读取用户配置
  2. startOnLoad: true 让 Mermaid 页面加载时自动渲染

高度定制化

如果插件无法满足需求，可以不安装此插件，直接使用 Hexo 的 Script 功能。适用场景：

  • 自定义 Mermaid 配置（如 theme、securityLevel、fontFamily）
  • 修改选择器（如 querySelector: 'pre code.mermaid'）
  • 完全自定义渲染逻辑

在 scripts/ 目录下创建自定义脚本：

1
2
3
4
5
6
7
8
9
10
11
hexo.extend.injector.register('body_end', `
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({
    startOnLoad: true,
    theme: 'dark',
    securityLevel: 'loose',
    fontFamily: 'Arial'
  });
</script>
`, 'default');

安装使用

1
npm install hexo-markdown-mermaid

配置：

1
2
3
4
5
6
7
8
highlight:
  exclude_languages:
    - mermaid

mermaid:
  version: 11
  startOnLoad: true
  theme: default

详细文档见 GitHub。