通用说明：如何在「Markdown 服务端渲染 + 前端增强」架构的文章站中支持 Mermaid 图。

目标

• 正文用 fenced code 写图（语言标记 mermaid）
• 前台渲染为 SVG；语法错误时回退源码提示，不拖垮整页
• 多数文章无图时不加载大体积引擎，降低流量

整体链路

Markdown 原文
  → 服务端 Markdown→HTML（GFM，保留 language-mermaid 代码块）
  → 注入文章页
  → 若 HTML 含 language-mermaid：按需加载 Mermaid 引擎 + 薄封装脚本
  → 封装脚本调用 mermaid.render → 替换为 SVG

普通代码块仍走语法高亮；遇到 mermaid 语言时跳过高亮，交给渲染器处理。

模块分工

模块	职责
Markdown 引擎（如 Goldmark GFM）	输出 <pre><code class="language-mermaid">
代码高亮脚本	跳过 language-mermaid，避免误当 shell 上色
Mermaid 库（建议 11.x，mermaid.min.js）	解析与绘图
薄封装（如 doc-mermaid.js）	收集代码块、initialize、逐块 render、错误回退
静态资源 / 嵌入	单二进制或静态目录托管上述 JS；资源带版本 hash

按需加载

扫描服务端产出的 HTML：仅当出现 language-mermaid 时注入引擎与封装脚本。

后台预览可始终挂载脚本（编辑页低频、体积可接受），预览回调在高亮之后再调用封装的 init。

样式方向（可选）

推荐与站点色系统一，避免默认白底块过突兀，例如：

• 方案 A：subgraph / 画布贴近站点表面色
• 方案 B（更透气）：集群框与外框透明，仅节点轻填充（浅绿灰等）

用 theme: "base" + themeVariables（如 clusterBkg: transparent），并用少量 CSS 覆盖 .cluster rect、.edgeLabel 等。

前端渲染要点

1. mermaid.initialize({ startOnLoad: false, … })，由封装主动 render
2. 依次处理每个代码块；成功则插入 SVG，失败则显示错误文案并保留源码
3. securityLevel: "strict"（按安全策略选择）
4. 脚本顺序：引擎 → 封装；均 defer，保证加载完成后再初始化

作者写法

用围栏代码块，第一行语言为 mermaid，例如：

```mermaid
flowchart TB
  A[服务 A] --> B[服务 B]
```

未闭合的围栏会被 Markdown 校验拦住。

测试建议

• 含 / 不含 mermaid 的文章：确认仅前者加载引擎
• 高亮脚本不改动 mermaid 块可见文本
• 抽样 flowchart / sequence / gantt 等能出图
• 故意写错语法：有提示、页面仍可浏览

限制与升级

• 引擎体积较大（约数 MB 级），依赖按需加载
• 升级时替换官方 mermaid.min.js，并回归常用图类型
• 个别实验语法（如 architecture-beta）依赖版本，升级前对照官方文档

小结

服务端只做标准 Markdown 代码块；识别 language-mermaid 后按需加载官方引擎；薄封装负责渲染与容错；样式与站点主题对齐即可。