Mermaid 转 SVG
本文档详细介绍了如何在本项目中使用 Mermaid 图表并将其自动转换为 SVG 格式。
概述
本项目使用自动化脚本将 Markdown 文件中的 Mermaid 代码块转换为 SVG 图片，以提高页面加载速度和用户体验。
工作原理
- 扫描 Markdown 文件：脚本扫描
content/目录下的所有.md文件 - 识别 Mermaid 代码块：查找
````mermaid代码块 - 生成 SVG 文件：使用 Mermaid CLI 将图表转换为 SVG 格式
- 插入图片标签：在 Markdown 文件中插入对应的图片标签
- 优化尺寸：自动设置图片的宽度和高度属性
使用方法
1. 在 Markdown 中编写 Mermaid 图表
在 Markdown 文件中，你可以这样编写 Mermaid 图表：
```mermaid "流程图示例"
graph TD
A[开始] --> B{是否满足条件}
B -->|是 | C[执行操作 A]
B -->|否| D[执行操作B]
C --> E[结束]
D --> E
```
2. 运行转换脚本
# 只生成缺失的 SVG 文件（推荐）
npm run transform-mermaid
# 强制重新生成所有 SVG 文件
npm run transform-mermaid -- --force
# 或使用简写
npm run transform-mermaid -- -f
3. 自动生成的结果
脚本会自动：
- 生成基于内容哈希的 SVG 文件名（如：
a1b2c3d4.svg） - 在 Mermaid 代码块后插入图片标签
- 设置合适的宽度和高度属性
转换后的 Markdown 内容示例：
```mermaid "流程图示例"
graph TD
A[开始] --> B{是否满足条件}
B -->|是 | C[执行操作 A]
B -->|否| D[执行操作B]
C --> E[结束]
D --> E
```
{width=1920 height=1080}
配置说明
Mermaid 配置文件
项目根目录的 mermaid-config.json 文件定义了图表的样式配置：
主题设置
{
"theme": "base",
"themeVariables": {
"primaryColor": "#0a55a7",
"primaryTextColor": "white",
"primaryBorderColor": "gray",
"secondaryColor": "gray",
"clusterBkg": "#fafafa",
"nodeBorder": "transparent",
"actorBorder": "gray",
"textColor": "black",
"tertiaryTextColor": "black"
}
}
图表类型特定设置
- 流程图：节点间距、排序间距、曲线样式
- 序列图：角色边距、宽度、高度设置
- 类图：曲线样式设置
- 状态图：曲线样式设置
- 甘特图：曲线样式设置
圆角样式
配置文件中的 themeCSS 部分为所有图表元素添加了 10px 的圆角效果：
.node rect, .flowchart-node rect, .basic.label-container {
rx: 10px !important;
ry: 10px !important;
}
脚本功能详解
核心功能
- 智能文件扫描
- 递归扫描
content/目录 - 只处理
.md文件 -
跳过不包含 Mermaid 代码块的文件
-
哈希命名
- 基于 Mermaid 代码内容生成 MD5 哈希
- 确保相同内容的图表使用相同文件名
-
避免重复生成相同的 SVG 文件
-
尺寸优化
- 自动解析 SVG 的
viewBox或width/height属性 - 确保最小宽度为 1920px
-
按比例计算对应的高度
-
增量更新
- 默认只生成缺失的 SVG 文件
- 支持强制重新生成所有文件
- 避免不必要的重复工作
命令行参数
| 参数 | 描述 |
|---|---|
| 无参数 | 只生成缺失的 SVG 文件 |
--force | 强制重新生成所有 SVG 文件 |
-f | --force 的简写形式 |
环境兼容性
脚本自动检测 CI 环境并添加必要的 Puppeteer 配置：
const isCI = process.env.CI || process.env.GITHUB_ACTIONS;
const sandboxFlag = isCI ? ' --puppeteerConfig \'{"args":["--no-sandbox","--disable-setuid-sandbox"]}\'' : '';
支持的 Mermaid 图表类型
流程图（Flowchart）
graph TD
A[开始] --> B{决策}
B -->|是| C[操作1]
B -->|否| D[操作2]序列图（Sequence Diagram）
sequenceDiagram
participant A as 用户
participant B as 系统
A->>B: 发送请求
B-->>A: 返回响应类图（Class Diagram）
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+bark()
}
Animal <|-- Dog状态图（State Diagram）
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]甘特图（Gantt Chart）
gantt
title 项目时间表
dateFormat YYYY-MM-DD
section 设计
需求分析 :done, des1, 2024-01-01,2024-01-10
系统设计 :active, des2, 2024-01-11, 3d饼图（Pie Chart）
pie title 编程语言使用比例
"JavaScript" : 42.96
"Python" : 17.24
"Java" : 11.52
"TypeScript" : 9.15
"其他" : 19.13最佳实践
1. 为图表添加标题
为每个图表添加有意义的标题：
```mermaid "有意义的图表标题"
graph TD
A --> B
```
2. 使用语义化的节点标识
使用清晰的节点名称和标签：
```mermaid
graph TD
START[开始] --> VALIDATE{验证数据}
VALIDATE -->|通过 | PROCESS[处理数据]
VALIDATE -->|失败| ERROR[错误处理]
```
3. 合理使用子图
使用子图组织复杂的逻辑：
```mermaid
graph TB
subgraph "前端"
A[用户界面]
B[业务逻辑]
end
subgraph "后端"
C[API服务]
D[数据库]
end
A --> C
B --> C
C --> D
```
4. 适当添加样式
为图表添加自定义样式：
```mermaid
graph TD
A[开始] --> B{条件}
B -->|是 | C[成功]
B -->|否| D[失败]
classDef success fill:#d4edda,stroke:#28a745,stroke-width:2px
classDef error fill:#f8d7da,stroke:#dc3545,stroke-width:2px
class C success
class D error
```
故障排除
常见问题
- SVG 文件未生成
- 检查 Mermaid 语法是否正确
- 确认已安装
@mermaid-js/mermaid-cli -
查看终端错误输出
-
图片显示不正确
- 检查 SVG 文件是否存在
- 确认图片路径是否正确
-
验证 Markdown 语法
-
尺寸问题
- 检查 SVG 文件的
viewBox属性 - 确认脚本是否正确解析了尺寸
- 可以手动调整图片标签的
width和height属性
调试方法
- 查看详细输出
npm run transform-mermaid
- 检查生成的 SVG 文件
ls -la content/path/to/your/markdown/directory/*.svg
- 验证 Mermaid 语法
可以使用在线 Mermaid 编辑器验证语法：https://mermaid.live/
性能优化
1. 增量生成
默认情况下，脚本只生成缺失的 SVG 文件，避免重复工作。
2. 哈希缓存
使用内容哈希作为文件名，相同内容的图表共享同一个 SVG 文件。
3. 批量处理
脚本一次性处理所有 Markdown 文件，提高整体效率。
集成到构建流程
在 package.json 中，transform-mermaid 脚本可以集成到构建流程中：
{
"scripts": {
"prebuild": "npm run transform-mermaid",
"build": "hugo --environment production --minify && npm run compress-json"
}
}
这样在每次构建前都会自动转换 Mermaid 图表。
总结
通过使用这个自动化脚本，你可以：
- 在 Markdown 中直接编写 Mermaid 图表
- 自动生成优化的 SVG 文件
- 享受一致的视觉样式
- 提高页面加载性能
- 维护图表的可编辑性
这个工具大大简化了在静态网站中使用复杂图表的流程，让你能够专注于内容创作而不用担心技术细节。