# Mermaid

> 基于文本的声明式图表绘制语法，Maplen 架构拓扑与状态机可视化的内嵌引擎

- HTML: /wiki/mermaid/
- Markdown: /wiki/mermaid.md
- Aliases: Mermaid, 流程图, 状态图, 图表语法
- Updated: 2026.11.09

---

Mermaid 是一种基于 JavaScript 的声明式图表绘制工具，允许作者使用类似 [Markdown (.md)](/wiki/md.md) 的纯文本语法来定义和渲染复杂的图表。

在 [Maplen](/wiki/maplen.md) 的工程与架构手记中，Mermaid 是所有流程图、状态转移图与管线拓扑的标准技术选择。

## 为什么拒绝位图，拥抱 Mermaid 文本

在传统技术写作中，作者往往使用 Visio、Draw.io 或 Excalidraw 绘制图表，然后导出为 PNG/JPG 位图插入正文。这种模式存在明显的缺陷：
- **无法被 Git 追踪与 Diff**：图表变成了二进制黑盒，每一次细微修改都无法在提交历史中清晰对比；
- **维护成本极高**：半年后哪怕只是修改流程中的一个文字步骤，也必须重新打开绘图软件重新导出；
- **破坏暗色/亮色主题统一性**：位图底色固定，切换夜间模式时会刺眼地泛白。

通过 Mermaid，图表就是正文代码：
```mermaid
stateDiagram-v2
  [*] --> 取指
  取指 --> 译码
  译码 --> 执行
  执行 --> 写回
  写回 --> [*]
```

## Maplen 对 Mermaid 的封装与调优

在 Maplen 中，Mermaid 被封装为自定义 Astro 组件 ``：
1. **语义色自适应**：图表的背景、线条墨色、填充渐变均深度绑定 [四色](/wiki/four-colors.md) 视觉体系与全局 CSS 变量（`var(--color-bg)`、`var(--color-border)` 等），无缝跟随系统的亮色「褐页」与暗色「暖墨」；
2. **正交与紧凑排版**：遵循横平竖直的设计原则，将冗长的单向平铺管线规约重构为紧凑的矩阵与分层结构（如在 [技术选型与静态管道](/nodes/architecture-showcase.md) 中的三列矩阵图）；
3. **客户端无感渲染**：在 [MDX (.mdx)](/wiki/mdx.md) 中按需挂载，保障长文的渲染平滑。

## 官方网站与参考链接

- **官方网站**：[Mermaid 官方主页 (mermaid.js.org)](https://mermaid.js.org/)
- **在线演练场**：[Mermaid Live Editor (mermaid.live)](https://mermaid.live/)
- **开源仓库**：[GitHub - mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)