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 content:mermaid:transform

# 强制重新生成所有 SVG 文件
npm run content:mermaid:transform -- --force

# 或使用简写
npm run content:mermaid:transform -- -f

3. 自动生成的结果¶

脚本会自动：

生成基于内容哈希的 SVG 文件名（如：a1b2c3d4.svg）
在 Mermaid 代码块后插入图片标签
设置合适的宽度和高度属性

转换后的 Markdown 内容示例：

```mermaid "流程图示例"
graph TD
    A[开始] --> B{是否满足条件}
    B -->|是 | C[执行操作 A]
    B -->|否| D[执行操作B]
    C --> E[结束]
    D --> E
```

![流程图示例](a1b2c3d4.svg)
{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 content:mermaid:transform
```

检查生成的 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 content:mermaid:transform",
    "build": "hugo --environment production --minify && npm run search:index:compress"
  }
}

这样在每次构建前都会自动转换 Mermaid 图表。

总结¶

通过使用这个自动化脚本，你可以：

在 Markdown 中直接编写 Mermaid 图表
自动生成优化的 SVG 文件
享受一致的视觉样式
提高页面加载性能
维护图表的可编辑性

这个工具大大简化了在静态网站中使用复杂图表的流程，让你能够专注于内容创作而不用担心技术细节。