Mermaid 是一种基于 JavaScript 的声明式图表绘制工具，允许作者使用类似 Markdown (.md) 的纯文本语法来定义和渲染复杂的图表。
在 Maplen 的工程与架构手记中，Mermaid 是所有流程图、状态转移图与管线拓扑的标准技术选择。
为什么拒绝位图，拥抱 Mermaid 文本
在传统技术写作中，作者往往使用 Visio、Draw.io 或 Excalidraw 绘制图表，然后导出为 PNG/JPG 位图插入正文。这种模式存在明显的缺陷：
- 无法被 Git 追踪与 Diff：图表变成了二进制黑盒，每一次细微修改都无法在提交历史中清晰对比；
- 维护成本极高：半年后哪怕只是修改流程中的一个文字步骤，也必须重新打开绘图软件重新导出；
- 破坏暗色/亮色主题统一性：位图底色固定，切换夜间模式时会刺眼地泛白。
通过 Mermaid，图表就是正文代码：
stateDiagram-v2
[*] --> 取指
取指 --> 译码
译码 --> 执行
执行 --> 写回
写回 --> [*]Maplen 对 Mermaid 的封装与调优
在 Maplen 中，Mermaid 被封装为自定义 Astro 组件 <Mermaid />：
- 语义色自适应：图表的背景、线条墨色、填充渐变均深度绑定 四色 视觉体系与全局 CSS 变量（
var(--color-bg)、var(--color-border)等），无缝跟随系统的亮色「褐页」与暗色「暖墨」； - 正交与紧凑排版：遵循横平竖直的设计原则，将冗长的单向平铺管线规约重构为紧凑的矩阵与分层结构（如在 技术选型与静态管道 中的三列矩阵图）；
- 客户端无感渲染：在 MDX (.mdx) 中按需挂载，保障长文的渲染平滑。
官方网站与参考链接
Backlinks / 反向链接