Mermaid 图表

在 Hugo 中使用 Mermaid 创建图表的全面指南

本主题支持在 Markdown 内容中直接使用 Mermaid 图表。Mermaid 让你通过文本和代码来创建图表和可视化。

关于 Mermaid.js

本主题集成了 Mermaid.js（v11），可以基于 Markdown 代码块中的文本定义来渲染图表。Mermaid 是一个基于 JavaScript 的图表绘制工具，其文本语法受 Markdown 启发。

完整的语法文档请参阅 Mermaid.js 文档。

快速开始

要创建 Mermaid 图表，只需使用以 mermaid 作为语言标识符的围栏代码块：

1
2
3
4
5

```mermaid
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
```

页面加载时图表会自动渲染。

特性

  • 自动检测：仅当页面包含图表时才加载 Mermaid 脚本
  • 主题支持：图表自动适配浅色/深色模式
  • HTML 标签：支持在标签中使用 HTML 内容（如 <br/> 换行）
  • 可配置：可在站点配置中自定义版本、安全级别等

配置

你可以在站点配置中配置 Mermaid：

hugo.yaml：

1
2
3
4
5
6
7
8
9

params:
  article:
    mermaid:
      version: "11"           # CDN 上的 Mermaid 版本
      look: classic           # classic 或 handDrawn（手绘风格）
      lightTheme: default     # 浅色模式主题
      darkTheme: neutral      # 深色模式主题
      securityLevel: strict   # strict（默认）、loose、antiscript、sandbox
      htmlLabels: true        # 启用标签中的 HTML

hugo.toml：

1
2
3
4
5
6
7

[params.article.mermaid]
  version = "11"           # CDN 上的 Mermaid 版本
  look = "classic"         # classic 或 handDrawn（手绘风格）
  lightTheme = "default"   # 浅色模式主题
  darkTheme = "neutral"    # 深色模式主题
  securityLevel = "strict" # strict（默认）、loose、antiscript、sandbox
  htmlLabels = true        # 启用标签中的 HTML

其他全局选项

以下可选设置未指定时将使用 Mermaid 的默认值：

hugo.yaml：

1
2
3
4
5
6
7
8
9

params:
  article:
    mermaid:
      maxTextSize: 50000      # 最大文本大小（默认：50000）
      maxEdges: 500           # 允许的最大边数（默认：500）
      fontSize: 16            # 全局字体大小（像素，默认：16）
      fontFamily: "arial"     # 全局字体族
      curve: "basis"          # 线条曲线：basis、cardinal、linear（默认：basis）
      logLevel: 5             # 调试级别 0-5，0=debug，5=fatal（默认：5）

hugo.toml：

1
2
3
4
5
6
7

[params.article.mermaid]
  maxTextSize = 50000      # 最大文本大小（默认：50000）
  maxEdges = 500           # 允许的最大边数（默认：500）
  fontSize = 16            # 全局字体大小（像素，默认：16）
  fontFamily = "arial"     # 全局字体族
  curve = "basis"          # 线条曲线：basis、cardinal、linear（默认：basis）
  logLevel = 5             # 调试级别 0-5，0=debug，5=fatal（默认：5）

如需图表特定选项（如 flowchart.useMaxWidth），可直接在图表中使用 Mermaid 的 init 指令：

1
2
3
4
5

```mermaid
%%{init: {'flowchart': {'useMaxWidth': false}}}%%
flowchart LR
    A --> B
```

安全提示： 建议使用默认的 securityLevel: strict。仅当需要在图表中使用 <br/> 等 HTML 标签时，才设置为 loose。

可用主题

主题 描述
default 标准彩色主题
neutral 灰度配色，适合打印和深色模式
dark 专为深色背景设计
forest 绿色调色板
base 极简主题，可通过 themeVariables 自定义
null 完全禁用主题

自定义主题变量

如需完全控制，可使用 base 主题配合自定义变量：

hugo.yaml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

params:
  article:
    mermaid:
      lightTheme: base
      darkTheme: base
      lightThemeVariables:
        primaryColor: "#4a90d9"
        primaryTextColor: "#ffffff"
        lineColor: "#333333"
      darkThemeVariables:
        primaryColor: "#6ab0f3"
        primaryTextColor: "#ffffff"
        lineColor: "#cccccc"
        background: "#1a1a2e"

hugo.toml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[params.article.mermaid]
  lightTheme = "base"
  darkTheme = "base"

  [params.article.mermaid.lightThemeVariables]
    primaryColor = "#4a90d9"
    primaryTextColor = "#ffffff"
    lineColor = "#333333"

  [params.article.mermaid.darkThemeVariables]
    primaryColor = "#6ab0f3"
    primaryTextColor = "#ffffff"
    lineColor = "#cccccc"
    background = "#1a1a2e"

常用变量：primaryColor、secondaryColor、tertiaryColor、primaryTextColor、lineColor、background、fontFamily

注意： 主题变量仅适用于 base 主题，且必须使用十六进制颜色值（如 #ff0000）。

图表类型

流程图

流程图是最常用的图表类型。使用 graph 或 flowchart 配合方向指示符：

  • TD 或 TB：从上到下
  • BT：从下到上
  • LR：从左到右
  • RL：从右到左

时序图

非常适合展示组件之间的交互：

类图

可视化类结构和关系：

状态图

建模状态机和状态转换：

实体关系图

记录数据库架构：

甘特图

规划和跟踪项目进度：

饼图

展示比例数据：

Git 图

可视化 Git 分支策略：

思维导图

创建层级思维导图：

时间线

展示时间顺序的事件：

高级功能

标签中使用 HTML

要在标签中使用 HTML，必须在站点配置中设置 securityLevel: loose：

hugo.yaml：

1
2
3
4
5

params:
  article:
    mermaid:
      securityLevel: loose
      htmlLabels: true

hugo.toml：

1
2
3

[params.article.mermaid]
  securityLevel = "loose"
  htmlLabels = true

然后就可以使用 <br/> 等 HTML 标签来换行：

1
2
3
4

```mermaid
graph TD
    A[第一行<br/>第二行] --> B[<b>加粗</b>文本]
```

单图主题覆盖

使用 Mermaid 的前置元数据为特定图表覆盖主题：

1
2
3
4
5

```mermaid
%%{init: {'theme': 'forest'}}%%
graph TD
    A[开始] --> B[结束]
```

使用 style 内联样式

你可以使用 style 指令直接在图表中为单个节点设置样式：

1
2
3
4
5
6
7

```mermaid
flowchart LR
    A[开始] --> B[处理] --> C[结束]
    style A fill:#4ade80,stroke:#166534,color:#000
    style B fill:#60a5fa,stroke:#1e40af,color:#000
    style C fill:#f87171,stroke:#991b1b,color:#fff
```

效果：

样式属性包括：

  • fill - 背景色
  • stroke - 边框颜色
  • stroke-width - 边框粗细
  • color - 文本颜色
  • stroke-dasharray - 虚线边框（如 5 5）

使用 CSS 类样式

你可以使用 classDef 定义可复用的样式，通过 :::className 来应用：

1
2
3
4
5
6
7

```mermaid
flowchart LR
    A:::success --> B:::info --> C:::warning
    classDef success fill:#4ade80,stroke:#166534,color:#000
    classDef info fill:#60a5fa,stroke:#1e40af,color:#000
    classDef warning fill:#fbbf24,stroke:#92400e,color:#000
```

效果：

子图

将相关节点分组：

主题切换

本主题会自动检测站点的浅色/深色模式偏好，并相应地调整 Mermaid 图表主题：

  • 浅色模式：使用 default Mermaid 主题
  • 深色模式：使用 dark Mermaid 主题（可配置）

尝试切换主题开关，实时查看图表更新！

复杂示例

以下是一个包含子图、HTML 标签、表情符号和自定义样式的示例：

注意： 此示例需要 securityLevel: loose 才能使 HTML 标签和样式生效。

已知限制

深色模式主题

Mermaid.js 的内置主题存在一些限制：

  • dark 主题（默认）：文本对比度最佳，但某些图表背景可能偏棕色（如甘特图）
  • neutral 主题：背景颜色更好，但某些文本（标签、图例）的对比度可能降低

如需完全控制，请使用 base 主题配合自定义变量：

hugo.yaml：

1
2
3
4
5
6
7
8
9

params:
  article:
    mermaid:
      darkTheme: base
      darkThemeVariables:
        primaryColor: "#1f2937"
        primaryTextColor: "#ffffff"
        lineColor: "#9ca3af"
        textColor: "#e5e7eb"

hugo.toml：

1
2
3
4
5
6
7
8

[params.article.mermaid]
  darkTheme = "base"

  [params.article.mermaid.darkThemeVariables]
    primaryColor = "#1f2937"
    primaryTextColor = "#ffffff"
    lineColor = "#9ca3af"
    textColor = "#e5e7eb"

随着 Mermaid.js 的发展，我们计划在未来的更新中改进深色模式主题。

故障排查

图表没有渲染？

  1. 确保使用的是以 mermaid 为语言标识的围栏代码块
  2. 检查浏览器的控制台是否有语法错误
  3. 在 Mermaid Live Editor 中验证 Mermaid 语法

标签中的 HTML 不生效？

标签中使用 HTML 需要 securityLevel: loose。请更新配置：

hugo.yaml：

1
2
3
4
5

params:
  article:
    mermaid:
      securityLevel: loose
      htmlLabels: true

hugo.toml：

1
2
3

[params.article.mermaid]
  securityLevel = "loose"
  htmlLabels = true

警告： 使用 loose 安全级别允许在图表中使用 HTML。仅在信任图表内容来源时使用。

语法错误？

Mermaid 对语法要求严格。常见问题：

  • 箭头周围缺少空格
  • 括号或引号未闭合
  • 无效的节点 ID（避免使用特殊字符）

相关资源

© 2020 - 2026 琪琪格 blog
使用 Hugo 构建
主题 Stack 由 Jimmy 设计