mermaid-js/mermaid

项目介绍

Mermaid 是一个 JavaScript 图表工具：用类 Markdown 的文本描述图形，再由渲染器生成图表。它主要解决文档和图表容易过期的问题——把图写成文本后，图表可以随代码和文档一起进入版本控制，修改时能像代码一样查看 diff、参与评审。适用对象是开发者和技术文档作者，也支持非程序员通过在线编辑器直接画图。

README 列出 20 多种图表类型，包括流程图、时序图、类图、状态图、ER 图、甘特图、饼图、Git graph、思维导图、时间线和桑基图，并支持主题、颜色和布局方向等定制 source:53。流程图和时序图的示例给出了可直接渲染的 mermaid 代码块写法 source:59；GitHub 等平台也支持在 Markdown 中直接渲染 Mermaid source:46。

快速使用

不安装任何东西也可以先试用：打开在线编辑器，粘贴一段图表定义，查看渲染结果。最小流程图示例：

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

这段定义也出现在 README 示例中 source:60。若要集成到项目里，先执行 npm install mermaid 安装 npm 包（包名为 mermaid source:5），然后在页面中引入并初始化库，把图表定义和目标元素传给渲染 API，再将返回的 SVG 插入页面。具体 API 调用签名见官方使用文档 source:48；入门流程可参考 Getting Started source:8。

使用约束

图表最终以浏览器内 SVG 的形式呈现，因此运行环境需要 JavaScript 和可插入的 DOM 元素。对于展示外部用户内容的公开站点，文档建议启用沙箱 iframe 安全级别：它能阻止图表定义中的恶意 JavaScript 执行，但同时会禁用部分交互功能；项目会对输入做清洗并持续改进，但无法保证不存在绕过方式 source:39。安全问题应通过文档给出的专用邮箱私下报告，而不是公开提交 source:40。

项目采用 MIT 许可证。布局和绘制能力主要依赖 d3 与 dagre-d3，时序图的语法来自另一个项目 source:41。命令行工具和在线编辑器是独立项目，不在本仓库内 source:37。

HotRepo 点评

本站记录到的相关讨论是 2025 年一条 255 分、107 条评论的 Hacker News 帖子：有评论者把它用在 GitHub PR、Notion 和 Obsidian 文档的内联图表里，也有人用多模态模型把手绘的流程草图转成 Mermaid 文本后手工微调 source:44049619。这些是 2025 年的个人使用经验，不代表项目质量。榜单方面，该仓库在 2026-11-04 进入 TypeScript 日榜，当日新增 23 Star，这只是单日快照，不足以判断趋势。项目已有约 9.1 万 Star 和 9.4 千 Fork，属于长期维护的项目；更实际的观察是，它「文本定义、渲染器出图」的方式适合图表需要随代码一起评审和更新的文档工作流。