Mermaid 使用指南基于 Markdown 风格文本渲染图表的 JavaScript 工具详解【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于仓库内官方介绍文档 docs/intro/index.md 展开系统讲解 Mermaid 的定位与适用场景、全部核心图表类型的语法示例、CDN 与 npm 两种部署方式、从源码层面验证的 sandbox 安全模型以及项目的开发、测试与发布流程。读完后你将能够独立选型并落地 Mermaid既会用mermaid.initialize在页面中自动渲染classmermaid节点也能理解其文本解析、图表类型检测与沙箱渲染的底层机制。一、Mermaid 是什么让文档跟上开发速度Mermaid 是一个基于 JavaScript 的绘图与图表工具它使用受 Markdown 启发的文本定义来创建和修改图表。其核心目标是帮助文档跟上开发节奏help documentation catch up with development。官方文档将绘图与文档维护描述为一个两难困境Doc-Rot绘制和撰写文档会耗费宝贵的开发者时间并且很快就会过时但没有图表和文档又会损害生产力、妨碍组织知识的沉淀。Mermaid 的解法是让图表以可轻易修改的文本形式存在图表定义就是纯文本可以纳入版本控制、参与代码评审甚至嵌入生产脚本中随代码一起变更。此外即使是非程序员也可以通过 Mermaid Live Editor 轻松创建复杂图表。如果你熟悉 Markdown学习 Mermaid 语法不会有太大障碍完整的语法规则可参考 语法参考入门示例可参考 快速上手 与 使用说明。从源码结构看Mermaid 的渲染管线由三个环节构成部署Deployment→ 语法Syntax→ 配置Configuration。这一划分在 docs/intro/getting-started.md 中明确阐述“Mermaid is composed of three parts”而图表类型则由解析器根据定义首行的声明语句来判定——这是理解后文“图表类型”一节的钥匙。二、支持的图表类型与语法示例介绍文档中给出了十类图表的完整示例。每一段定义都以图表类型声明行开头如graph TD、sequenceDiagram、gantt随后是图表内容的具体定义。解析器依据该声明决定调用哪一套解析规则——从源码结构看各图表类型均通过registerDiagram(id, diagram, detector)注册到 diagram-orchestration.ts再由 detectType.ts 中的detectType函数依据首行文本判定类型。以下逐一给出官方示例及其对应的语法文档入口链接均为仓库根目录相对路径。2.1 流程图Flowchart语法文档flowchart.mdgraph TD表示自上而下top-down方向的流程图A--B定义节点间的带箭头连线。语句以分号结尾属于 Mermaid 的典型风格。2.2 时序图Sequence diagram语法文档sequenceDiagram.md示例覆盖了参与者声明participant、同步/异步消息-与--、循环块loop ... end以及注释Note right of等时序图核心元素。2.3 用例图Use case diagram语法文档usecase.md注意该示例使用usecase-beta声明表明用例图目前以 beta 通道提供direction LR控制布局方向actor声明参与者Customer -- Checkout表示参与者与用例之间的关联。2.4 甘特图Gantt diagram语法文档gantt.md示例展示了日期格式dateFormat、排除日excludes weekdays、任务状态done/active、依赖关系after des2与时长3d、5d等甘特图关键特性。2.5 类图Class diagram语法文档classDiagram.md示例涵盖了 UML 常见的关系符号|--继承、*--组合、o--聚合、..依赖、--|实现以及带冒号的关系标签和成员方法/字段声明。2.6 Git 图Git graph语法文档gitgraph.mdgitGraph用于描述 Git 提交历史commit推进提交branch develop派生分支checkout main切换分支——适合把分支模型直接写进文档。2.7 实体关系图ER Diagram实验性语法文档entityRelationshipDiagram.md关系符号采用|o、}o、|{等基数记号表达一对一、一对多、多对多。原文档将该类型标记为 experimental实验性使用时需留意稳定性。2.8 用户旅程图User Journey Diagram语法文档userJourney.md每个任务后的数字1–5表示该步骤的评分其后冒号列出参与人可多人逗号分隔。2.9 象限图Quadrant Chart语法文档quadrantChart.md坐标值均为 0–1 之间的归一化坐标x-axis/y-axis定义轴端语义四个象限可各自命名适合做优先级、影响力一类的二维定位分析。2.10 XY 图表XY Chart语法文档xyChart.mdxychart-beta声明表示该类型走 beta 通道。x-axis接受分类标签数组y-axis指定范围本例为 4000 → 11000随后bar与line分别绘制柱状与折线序列。更多图表与完整示例集合可查阅 示例文档。三、安装与部署3.1 通过 CDN 引入CDN 地址模板为https://cdn.jsdelivr.net/npm/mermaidversion/dist/将version替换为目标版本号即可锁定版本原文档同时给出按大版本选择的示例mermaid11。需要说明的是以当前仓库为准根目录 package.json 中 monorepo 版本为10.2.4version: 10.2.4因此选择具体版本时应以实际发布的 npm 包版本为准并按需锁定避免大版本升级带来的行为差异。3.2 通过包管理器安装依赖方式官方文档给出了三种包管理器的安装命令NPMnpm i mermaidYarnyarn add mermaidPnpmpnpm add mermaid部署前提安装 Node.js带 npm 的环境。从源码结构看当前仓库自身采用 pnpm 10.x 管理 monorepo根 package.json 中packageManager字段声明pnpm10.30.3因此使用 pnpm 是与上游工具链最一致的本地开发选择。3.3 无 Bundler 部署script 标签 initialize这是最轻量的接入方式在 HTML 中插入带绝对地址的script标签并调用mermaid.initializescript typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid11/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /script关键在于startOnLoad: true这一配置它命令 Mermaid 解析器在页面加载后自动查找带有classmermaid的div或pre标签读取其中的图表/图表定义并将其渲染为 SVG。也就是说你只需要在 HTML 里写pre classmermaid graph TD; A--B; A--C; B--D; C--D; /pre页面加载完成后即自动完成解析与渲染。Mermaid API 的完整配置项可查阅 API 配置文档。四、从源码看安全模型sandbox 渲染介绍文档专门用一节Security and safe diagrams讨论了公共站点的安全风险从互联网用户处获取文本、稍后在浏览器中呈现存在用户内容内嵌恶意脚本被执行的风险。由于 Mermaid 图表定义中包含大量 HTML 字符标准 sanitize 流程会破坏图表本身因此官方采取了双层策略尽力消毒对传入的图表代码持续做 sanitize并不断完善该流程沙箱渲染为有外部用户的站点提供更高的安全级别将图表渲染在沙箱化sandboxed的 iframe 中阻止图表代码中的 JavaScript 被执行。代价是“鱼与熊掌不可兼得”——部分交互功能会连同潜在恶意代码一起被屏蔽。这一机制在源码中可以得到验证。mermaidAPI.ts 中定义了沙箱相关常量SECURITY_LVL_SANDBOX sandbox IFRAME_SANDBOX_OPTS allow-top-navigation-by-user-activation allow-popups IFRAME_NOT_SUPPORTED_MSG The iframe tag is not supported by your browser.以及核心的sandboxedIframe函数注释为 “Append an iFrame node to the given parentNode and set the id, style, and sandbox attributes”它通过.attr(sandbox, )设置 iframe 的沙箱属性。当配置进入沙箱模式时源码注释明确写道 “If we are in sandboxed mode, we do everything mermaid related in a (sandboxed) iFrame”——即所有 Mermaid 相关渲染都发生在带sandbox属性的 iframe 内部。该源码与文档描述相互印证沙箱不是文档层面的概念而是配置驱动的、真实生效的渲染路径。仓库中还存在配套的安全测试页面如 click_security_sandbox.html、click_security_loose.html 等与 XSS 回归用例xss.spec.js用于持续验证不同安全等级下的点击回调与注入防护行为进一步说明安全模型是项目长期维护的一等公民。漏洞报告渠道按照文档说明漏洞应通过邮件 securitymermaid.live 报告内容需包含问题描述、复现步骤、受影响版本以及已知的缓解措施。五、参与开发环境、测试与发布介绍文档给出了完整的项目级开发流程以下命令均来自该文档并可在本仓库根目录核对脚本定义见 package.json 的scripts段。5.1 环境要求使用 volta 管理 Node 版本外部工具原文档要求Node.jsvolta install nodepnpm 包管理器volta install pnpm5.2 开发安装git clone gitgithub.com:mermaid-js/mermaid.git cd mermaid # npx is required for first install as volta support for pnpm is not added yet. npx pnpm install pnpm test注意以上 clone 地址为上游仓库地址仅供了解流程本仓库只读镜像无需执行克隆。5.3 代码检查Lintpnpm lint项目使用 eslint官方建议安装编辑器插件获得实时 lint 结果。对照根 package.json 可确认lint脚本实际执行的是 eslint带缓存 jison 语法文件检查pnpm lint:jison对应 scripts/jison/lint.mts prettier 检查说明图表的 jison 语法文件也纳入了 lint 范围。5.4 测试Testpnpm test浏览器手动测试打开dist/index.html。从根 package.json 可以看到test脚本实际是pnpm lint vitest run——即先 lint 再运行 vitest 单元测试仓库同时维护了 Playwright 端到端测试playwright test配置见 playwright.config.ts以及位于 e2e/diagrams 下的大量.mmd视觉回归用例覆盖 flowchart、sequence、er、class、gantt 等全部图表类型文档中提到的 Argos / Applitools 视觉回归测试即服务于这一体系。5.5 发布Release对有权限的维护者更新package.json中的版本号然后执行npm publish。该命令会生成dist目录下的产物并发布到 npm。从源码结构看仓库内构建脚本pnpm build:esbuild见根 package.json负责打包生成dist产物发布流程还配合了 changesetchangeset:version/changeset:publish进行版本与 changelog 管理。六、生态与致谢6.1 姊妹项目介绍文档列出了与 Mermaid 核心的配套项目Mermaid Live Editor在线编辑与预览环境适合非程序员快速上手见 教程页面 的视频教程Mermaid CLI无头环境下生成图表的命令行工具Mermaid Tiny精简构建位于本仓库 packages/tiny适合只需要部分图表类型、在意包体积的场景Webpack / Parcel Demo展示在主流打包器中接入 Mermaid 的示例。社区集成清单见 社区集成文档可将 Mermaid 接入你常用的应用贡献指南见 贡献文档。6.2 致谢官方文档明确致谢了以下基础项目与个人d3 与 dagre-d3提供图形布局与绘制库js-sequence-diagram时序图语法的来源Jessica Peter甘特图渲染的起点与灵感Tyler Long自 2017 年 4 月起的合作者以及持续增长的贡献者群体。Mermaid 由 Knut Sveidqvist 创建初衷是“easier documentation”——为更容易的文档化服务。七、小结主题关键要点依据定位基于 JavaScript、以 Markdown 风格文本渲染图表解决 Doc-Rotdocs/intro/index.md图表类型流程图、时序、用例、甘特、类图、Git 图、ER实验性、旅程、象限、XYbeta十类核心示例本文第二节各docs/syntax/*.md部署CDNjsDelivr 模板 版本占位符npm/yarn/pnpmscript 标签 initialize({ startOnLoad: true })自动渲染classmermaid节点docs/intro/index.md、docs/config/setup/README.md安全消毒 sandbox 模式沙箱 iframe 渲染交互功能受限packages/mermaid/src/mermaidAPI.ts开发流程volta pnpmpnpm testlint vitest、Playwright 视觉回归、npm publish 发布package.json、playwright.config.ts掌握以上内容你就可以按“选型 → 部署 → 写定义 → 配置 → 安全加固”的完整链路使用 Mermaid并在需要深入定制时沿本文给出的源码与测试路径继续下钻。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mermaid 使用指南：基于 Markdown 风格文本渲染图表的 JavaScript 工具详解
Mermaid 使用指南基于 Markdown 风格文本渲染图表的 JavaScript 工具详解【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于仓库内官方介绍文档 docs/intro/index.md 展开系统讲解 Mermaid 的定位与适用场景、全部核心图表类型的语法示例、CDN 与 npm 两种部署方式、从源码层面验证的 sandbox 安全模型以及项目的开发、测试与发布流程。读完后你将能够独立选型并落地 Mermaid既会用mermaid.initialize在页面中自动渲染classmermaid节点也能理解其文本解析、图表类型检测与沙箱渲染的底层机制。一、Mermaid 是什么让文档跟上开发速度Mermaid 是一个基于 JavaScript 的绘图与图表工具它使用受 Markdown 启发的文本定义来创建和修改图表。其核心目标是帮助文档跟上开发节奏help documentation catch up with development。官方文档将绘图与文档维护描述为一个两难困境Doc-Rot绘制和撰写文档会耗费宝贵的开发者时间并且很快就会过时但没有图表和文档又会损害生产力、妨碍组织知识的沉淀。Mermaid 的解法是让图表以可轻易修改的文本形式存在图表定义就是纯文本可以纳入版本控制、参与代码评审甚至嵌入生产脚本中随代码一起变更。此外即使是非程序员也可以通过 Mermaid Live Editor 轻松创建复杂图表。如果你熟悉 Markdown学习 Mermaid 语法不会有太大障碍完整的语法规则可参考 语法参考入门示例可参考 快速上手 与 使用说明。从源码结构看Mermaid 的渲染管线由三个环节构成部署Deployment→ 语法Syntax→ 配置Configuration。这一划分在 docs/intro/getting-started.md 中明确阐述“Mermaid is composed of three parts”而图表类型则由解析器根据定义首行的声明语句来判定——这是理解后文“图表类型”一节的钥匙。二、支持的图表类型与语法示例介绍文档中给出了十类图表的完整示例。每一段定义都以图表类型声明行开头如graph TD、sequenceDiagram、gantt随后是图表内容的具体定义。解析器依据该声明决定调用哪一套解析规则——从源码结构看各图表类型均通过registerDiagram(id, diagram, detector)注册到 diagram-orchestration.ts再由 detectType.ts 中的detectType函数依据首行文本判定类型。以下逐一给出官方示例及其对应的语法文档入口链接均为仓库根目录相对路径。2.1 流程图Flowchart语法文档flowchart.mdgraph TD表示自上而下top-down方向的流程图A--B定义节点间的带箭头连线。语句以分号结尾属于 Mermaid 的典型风格。2.2 时序图Sequence diagram语法文档sequenceDiagram.md示例覆盖了参与者声明participant、同步/异步消息-与--、循环块loop ... end以及注释Note right of等时序图核心元素。2.3 用例图Use case diagram语法文档usecase.md注意该示例使用usecase-beta声明表明用例图目前以 beta 通道提供direction LR控制布局方向actor声明参与者Customer -- Checkout表示参与者与用例之间的关联。2.4 甘特图Gantt diagram语法文档gantt.md示例展示了日期格式dateFormat、排除日excludes weekdays、任务状态done/active、依赖关系after des2与时长3d、5d等甘特图关键特性。2.5 类图Class diagram语法文档classDiagram.md示例涵盖了 UML 常见的关系符号|--继承、*--组合、o--聚合、..依赖、--|实现以及带冒号的关系标签和成员方法/字段声明。2.6 Git 图Git graph语法文档gitgraph.mdgitGraph用于描述 Git 提交历史commit推进提交branch develop派生分支checkout main切换分支——适合把分支模型直接写进文档。2.7 实体关系图ER Diagram实验性语法文档entityRelationshipDiagram.md关系符号采用|o、}o、|{等基数记号表达一对一、一对多、多对多。原文档将该类型标记为 experimental实验性使用时需留意稳定性。2.8 用户旅程图User Journey Diagram语法文档userJourney.md每个任务后的数字1–5表示该步骤的评分其后冒号列出参与人可多人逗号分隔。2.9 象限图Quadrant Chart语法文档quadrantChart.md坐标值均为 0–1 之间的归一化坐标x-axis/y-axis定义轴端语义四个象限可各自命名适合做优先级、影响力一类的二维定位分析。2.10 XY 图表XY Chart语法文档xyChart.mdxychart-beta声明表示该类型走 beta 通道。x-axis接受分类标签数组y-axis指定范围本例为 4000 → 11000随后bar与line分别绘制柱状与折线序列。更多图表与完整示例集合可查阅 示例文档。三、安装与部署3.1 通过 CDN 引入CDN 地址模板为https://cdn.jsdelivr.net/npm/mermaidversion/dist/将version替换为目标版本号即可锁定版本原文档同时给出按大版本选择的示例mermaid11。需要说明的是以当前仓库为准根目录 package.json 中 monorepo 版本为10.2.4version: 10.2.4因此选择具体版本时应以实际发布的 npm 包版本为准并按需锁定避免大版本升级带来的行为差异。3.2 通过包管理器安装依赖方式官方文档给出了三种包管理器的安装命令NPMnpm i mermaidYarnyarn add mermaidPnpmpnpm add mermaid部署前提安装 Node.js带 npm 的环境。从源码结构看当前仓库自身采用 pnpm 10.x 管理 monorepo根 package.json 中packageManager字段声明pnpm10.30.3因此使用 pnpm 是与上游工具链最一致的本地开发选择。3.3 无 Bundler 部署script 标签 initialize这是最轻量的接入方式在 HTML 中插入带绝对地址的script标签并调用mermaid.initializescript typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid11/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /script关键在于startOnLoad: true这一配置它命令 Mermaid 解析器在页面加载后自动查找带有classmermaid的div或pre标签读取其中的图表/图表定义并将其渲染为 SVG。也就是说你只需要在 HTML 里写pre classmermaid graph TD; A--B; A--C; B--D; C--D; /pre页面加载完成后即自动完成解析与渲染。Mermaid API 的完整配置项可查阅 API 配置文档。四、从源码看安全模型sandbox 渲染介绍文档专门用一节Security and safe diagrams讨论了公共站点的安全风险从互联网用户处获取文本、稍后在浏览器中呈现存在用户内容内嵌恶意脚本被执行的风险。由于 Mermaid 图表定义中包含大量 HTML 字符标准 sanitize 流程会破坏图表本身因此官方采取了双层策略尽力消毒对传入的图表代码持续做 sanitize并不断完善该流程沙箱渲染为有外部用户的站点提供更高的安全级别将图表渲染在沙箱化sandboxed的 iframe 中阻止图表代码中的 JavaScript 被执行。代价是“鱼与熊掌不可兼得”——部分交互功能会连同潜在恶意代码一起被屏蔽。这一机制在源码中可以得到验证。mermaidAPI.ts 中定义了沙箱相关常量SECURITY_LVL_SANDBOX sandbox IFRAME_SANDBOX_OPTS allow-top-navigation-by-user-activation allow-popups IFRAME_NOT_SUPPORTED_MSG The iframe tag is not supported by your browser.以及核心的sandboxedIframe函数注释为 “Append an iFrame node to the given parentNode and set the id, style, and sandbox attributes”它通过.attr(sandbox, )设置 iframe 的沙箱属性。当配置进入沙箱模式时源码注释明确写道 “If we are in sandboxed mode, we do everything mermaid related in a (sandboxed) iFrame”——即所有 Mermaid 相关渲染都发生在带sandbox属性的 iframe 内部。该源码与文档描述相互印证沙箱不是文档层面的概念而是配置驱动的、真实生效的渲染路径。仓库中还存在配套的安全测试页面如 click_security_sandbox.html、click_security_loose.html 等与 XSS 回归用例xss.spec.js用于持续验证不同安全等级下的点击回调与注入防护行为进一步说明安全模型是项目长期维护的一等公民。漏洞报告渠道按照文档说明漏洞应通过邮件 securitymermaid.live 报告内容需包含问题描述、复现步骤、受影响版本以及已知的缓解措施。五、参与开发环境、测试与发布介绍文档给出了完整的项目级开发流程以下命令均来自该文档并可在本仓库根目录核对脚本定义见 package.json 的scripts段。5.1 环境要求使用 volta 管理 Node 版本外部工具原文档要求Node.jsvolta install nodepnpm 包管理器volta install pnpm5.2 开发安装git clone gitgithub.com:mermaid-js/mermaid.git cd mermaid # npx is required for first install as volta support for pnpm is not added yet. npx pnpm install pnpm test注意以上 clone 地址为上游仓库地址仅供了解流程本仓库只读镜像无需执行克隆。5.3 代码检查Lintpnpm lint项目使用 eslint官方建议安装编辑器插件获得实时 lint 结果。对照根 package.json 可确认lint脚本实际执行的是 eslint带缓存 jison 语法文件检查pnpm lint:jison对应 scripts/jison/lint.mts prettier 检查说明图表的 jison 语法文件也纳入了 lint 范围。5.4 测试Testpnpm test浏览器手动测试打开dist/index.html。从根 package.json 可以看到test脚本实际是pnpm lint vitest run——即先 lint 再运行 vitest 单元测试仓库同时维护了 Playwright 端到端测试playwright test配置见 playwright.config.ts以及位于 e2e/diagrams 下的大量.mmd视觉回归用例覆盖 flowchart、sequence、er、class、gantt 等全部图表类型文档中提到的 Argos / Applitools 视觉回归测试即服务于这一体系。5.5 发布Release对有权限的维护者更新package.json中的版本号然后执行npm publish。该命令会生成dist目录下的产物并发布到 npm。从源码结构看仓库内构建脚本pnpm build:esbuild见根 package.json负责打包生成dist产物发布流程还配合了 changesetchangeset:version/changeset:publish进行版本与 changelog 管理。六、生态与致谢6.1 姊妹项目介绍文档列出了与 Mermaid 核心的配套项目Mermaid Live Editor在线编辑与预览环境适合非程序员快速上手见 教程页面 的视频教程Mermaid CLI无头环境下生成图表的命令行工具Mermaid Tiny精简构建位于本仓库 packages/tiny适合只需要部分图表类型、在意包体积的场景Webpack / Parcel Demo展示在主流打包器中接入 Mermaid 的示例。社区集成清单见 社区集成文档可将 Mermaid 接入你常用的应用贡献指南见 贡献文档。6.2 致谢官方文档明确致谢了以下基础项目与个人d3 与 dagre-d3提供图形布局与绘制库js-sequence-diagram时序图语法的来源Jessica Peter甘特图渲染的起点与灵感Tyler Long自 2017 年 4 月起的合作者以及持续增长的贡献者群体。Mermaid 由 Knut Sveidqvist 创建初衷是“easier documentation”——为更容易的文档化服务。七、小结主题关键要点依据定位基于 JavaScript、以 Markdown 风格文本渲染图表解决 Doc-Rotdocs/intro/index.md图表类型流程图、时序、用例、甘特、类图、Git 图、ER实验性、旅程、象限、XYbeta十类核心示例本文第二节各docs/syntax/*.md部署CDNjsDelivr 模板 版本占位符npm/yarn/pnpmscript 标签 initialize({ startOnLoad: true })自动渲染classmermaid节点docs/intro/index.md、docs/config/setup/README.md安全消毒 sandbox 模式沙箱 iframe 渲染交互功能受限packages/mermaid/src/mermaidAPI.ts开发流程volta pnpmpnpm testlint vitest、Playwright 视觉回归、npm publish 发布package.json、playwright.config.ts掌握以上内容你就可以按“选型 → 部署 → 写定义 → 配置 → 安全加固”的完整链路使用 Mermaid并在需要深入定制时沿本文给出的源码与测试路径继续下钻。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考