# Mermaid

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

- Site: https://maplen.top/
- Page: https://maplen.top/wiki/mermaid/
- LLM: https://maplen.top/wiki/mermaid/llms.txt
- Author: 红枫 (Maple)
- Audience: AI agents / LLM tools
- Updated: 2026.11.09
- Markdown: https://maplen.top/wiki/mermaid.md

## Content

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)

## Backlinks

- [脚本交互与代码展示：8 位微处理器动态演示](https://maplen.top/nodes/computer-showcase/llms.txt): 基于网站的 JS 脚本组件支持，构建 8 位 CPU 状态机可视化演示，并测试代码高亮、复制与悬停黑块功能
- [笔墨与纸面：Maplen 的排版美学与文本地基](https://maplen.top/nodes/markdown-showcase/llms.txt): 从字形微调、行间呼吸到 Wiki 双向链接与微观句子锚点，为长篇沉浸阅读筑牢坚实的地基
- [架构图与系统流向：Maplen 是如何运转的](https://maplen.top/nodes/architecture-showcase/llms.txt): 从 4N 正交体系到静态优先流水线，用 Mermaid 图表全景解析我为 Maplen 搭建的底层逻辑