让 Hugo 博客支持 Mermaid 图表

Fri, 01 Aug 2025 10:00:00 +0000

之前写过一篇文章, 讲怎么用 Shortcodes 给博客加 ECharts 图表. 但日常写技术文章更常需要的是流程图、时序图这类"文本即图形"的图. Mermaid 正好干这个: 用几行文本描述一张图, 不用拖画布, 不用贴截图.

而且现在 Hugo 有比 Shortcodes 更优雅的方案——代码块渲染钩子 (code block render hook). 从 Hugo v0.123 开始, 可以自定义代码块的渲染, 拦截 mermaid 语言的围栏代码块, 在构建时直接输出成可渲染的图形容器.

一、创建渲染钩子

在项目根目录创建 layouts/_default/_markup/render-codeblock.html:

{{ $lang := .Type | default "plain" }}
{{ if eq $lang "mermaid" }}
<pre class="mermaid" role="img" aria-label="Mermaid diagram">{{ .Inner }}</pre>
{{ if not (.Page.Store.Get "mermaidLoaded") }}
{{ .Page.Store.Set "mermaidLoaded" true }}
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({
 startOnLoad: false,
 theme: 'base',
 themeVariables: {
 background: '#1d1f21',
 primaryColor: '#282c34',
 primaryBorderColor: '#3e4147',
 primaryTextColor: '#c9cacc',
 lineColor: '#5a5f66',
 edgeLabelBackground: '#1d1f21'
 }
});
mermaid.run({ querySelector: 'pre.mermaid' });
</script>
{{ end }}
{{ else }}
{{ highlight .Inner .Type }}
{{ end }}

这个模板做的事很简单:

图表 on Time Friend

让 Hugo 博客支持 Mermaid 图表

一、创建渲染钩子