图表即代码：Foojay 新增 Mermaid 图表支持

有些东西展示出来比描述容易得多。一个请求穿越三个服务、一个类层次结构、连接所经历的各种状态：写一段文字来解释这些需要花费很大力气，而且仍然会让读者自己去拼出整幅图景。

通常的答案是打开绘图工具，导出 PNG，然后把它放进文章文件夹。这样做可行，而且迄今为止大多数 Foojay 文章都是这么做的。但这也意味着该图现在成了一个二进制文件：没人能审阅它，没人能修正其中的错别字，也没人能在不再次找到原始文件的情况下更新它——前提是他们还留着那个原始文件。

所以 Foojay 文章现在支持 Mermaid：你把图表写成围栏代码块，它就会渲染成真正的图表。感谢 Maximillian Arruda 提出这个需求。

简短版

把你的图表放进一个 mermaid 代码块中：

```mermaid
graph LR
    A[Source] --> B[javac]
    B --> C[Bytecode]
    C --> D{JIT?}
    D -->|Hot| E[Native code]
    D -->|Cold| F[Interpreter]
```

文章就会显示如下：

graph LR
    A[Source] --> B[javac]
    B --> C[Bytecode]
    C --> D{JIT?}
    D -->|Hot| E[Native code]
    D -->|Cold| F[Interpreter]

无需设置 frontmatter 标志，也无需启用任何东西。如果你的文章包含 mermaid 块，你就会得到图表；如果不包含，则不会额外加载任何内容。

一些示例

Mermaid 涵盖许多图表类型。以下是 Foojay 所发布文章中经常出现的几种。查看本文源码即可看到生成这些图表的代码块。

// TODO 在本文合并后添加 GitHub 仓库链接。

时序图

对于任何涉及多个流程的场景来说，这大概是所有类型中最有用的——也是手工绘制起来最繁琐的，因为每一次改动都会移动其下方的每一根箭头。

sequenceDiagram
    autonumber
    participant C as Client
    participant G as Gateway
    participant S as Order Service
    participant D as Database

    C->>G: POST /orders
    G->>S: createOrder(...)
    S->>D: INSERT
    D-->>S: order id
    S-->>G: 201 Created
    G-->>C: 201 Created
    Note over S,D: Retried once on a<br/>constraint violation

类图

适合解释 API 形态或小型层次结构，而无需粘贴五个文件的源代码。

classDiagram
    class Shape {
        <<interface>>
        +double area()
    }
    class Circle {
        -double radius
        +double area()
    }
    class Rectangle {
        -double width
        -double height
        +double area()
    }
    Shape <|.. Circle
    Shape <|.. Rectangle

注意，接口是一个带有 <<interface>> 注解的 class——没有 interface 关键字，从 Java 转过来的人很容易在这里踩坑。

状态图

适用于任何有生命周期的对象——连接、会话、虚拟线程、构建。

stateDiagram-v2
    [*] --> New
    New --> Runnable: start()
    Runnable --> Running: scheduled
    Running --> Blocked: waits on monitor
    Blocked --> Runnable: monitor released
    Running --> Terminated: run() returns
    Terminated --> [*]

实体关系图

erDiagram
    AUTHOR ||--o{ ARTICLE : writes
    ARTICLE }o--|| CATEGORY : "filed under"
    ARTICLE {
        string slug
        string title
        date published
    }

甘特图

便于展示发布日程或迁移计划。

gantt
    dateFormat YYYY-MM-DD
    axisFormat %b
    title A JDK upgrade, roughly
    section Preparation
    Inventory dependencies :a1, 2026-09-01, 30d
    Update build tooling   :a2, after a1, 20d
    section Migration
    Compile on the new JDK :b1, after a2, 25d
    Run on the new JDK     :b2, after b1, 35d

为什么值得使用

代码块中的图表是可以审阅的。 Foojay 文章以拉取请求的形式提交。PNG 在 diff 中显示为“二进制文件已更改”；Mermaid 图表则显示为你修改的那些行。审阅者可以发现箭头方向错了，而你可以通过编辑一行来修复，而不必重新打开绘图工具。

它能保持正确。 当你描述的东西发生变化时，你只需编辑两个词，而不必重新创建一张图片。那些会变得过时的图表，正是更新起来代价高昂的图表。

它在两种主题下都清晰易读。 图表会跟随网站的浅色和深色主题，并在读者切换时重新绘制。导出的 PNG 只有一种永久不变的背景色，这就是为什么网上很多图表在深色页面中间成了一块白色矩形。

它始终保持清晰。 它是 SVG，因此可以缩放到读者使用的任何屏幕。

它就是你已经在用的同一套语法。 GitHub 和 GitLab 会在 issue、拉取请求和 README 中渲染 mermaid 块。你项目 README 中的图表可以原样粘贴到文章中。

需要了解的事项

提交前检查语法，可使用 Mermaid 在线编辑器。如果某个图表无法解析，在渲染后的文章中，该图表会被一条错误消息替换——页面其余部分没有问题，但图表就不显示了。
不要硬编码颜色。 Mermaid 支持样式指令，但为浅色背景选择的颜色往往会在深色背景上消失。默认主题已经会跟随读者的选择。
保持图表小巧。 一个包含四十个节点的图表在手机上无法阅读。几个小图表胜过一个大得离谱的图表。
图表不能替代替代文本（alt text）。 如果图表承载了关键信息，也要在周围的文字中说明——这有助于屏幕阅读器用户，也有助于在火车上快速浏览的读者。还有三件值得了解的事：
无需开启任何开关。 不需要 frontmatter 标志——写出围栏代码块就能得到图表。没有该代码块的页面根本不会加载图表库。
图表会跟随读者的主题，无论是浅色还是深色，并且会在读者切换时重新绘制。不要硬编码颜色。
如果语法无法解析，该图表会在原位置显示一条错误消息，文章其余部分不受影响。如果不确定，可以在在线编辑器中检查你的图表。

图片当然仍然没问题，也仍然是截图、照片以及任何手绘内容的最佳选择。但如果你过去因为画图太麻烦，而用三段文字来描述一个流程，现在不必再这样了。

为 Foojay 撰稿

Foojay 依靠贡献运转，这里的一切——包括这项功能——都是开放的。仓库中的 ../../template/post.md 记录了作者可用的所有格式化功能，包括 Mermaid；如何提交你的下一篇文章则介绍了整个流程。

如果你发现缺少什么，请提交 issue 或拉取请求。这项功能就是这样来的。

发现错误，或有内容要补充？在 GitHub 上编辑此页面 [LOADING...]
作者

参与讨论

Foojay [LOADING...]
3 位作者 · 2022年5月3日 · 15,308 次浏览

如何在 Foojay.io 上提交你的下一篇文章

Foojay Foojay [LOADING...]
2 位作者 · 2026年7月6日 · 1,561 次浏览

整理周：Foojay.io 有哪些变化

Foojay

分类导航

图表即代码：Foojay 新增 Mermaid 图表支持

简短版

一些示例

时序图

类图

状态图

实体关系图

甘特图

为什么值得使用

需要了解的事项

为 Foojay 撰稿

Frank Delporte

相关文章

如何在 Foojay.io 上提交你的下一篇文章

整理周：Foojay.io 有哪些变化

参与讨论

如何在 Foojay.io 上提交你的下一篇文章

整理周：Foojay.io 有哪些变化