Mermaid 图表引擎解析与部署实战用类 Markdown 文本编写可维护的流程图与架构图【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 是一款基于 JavaScript 的图表与可视化生成工具它以「类 Markdown」的文本定义作为输入借助解析器与渲染器将文本动态渲染为可交互的 SVG 图表。本文围绕 Mermaid 官方入门文档的核心内容展开讲解它诞生的动机对抗文档腐化、支持的图表生态、通过 CDN 与包管理器完成安装、在无打包器网页中调用 Mermaid API 的部署方案以及安全渲染、漏洞报告与源码级协作的完整链路帮助读者在各类 Web 应用与 Markdown 环境中落地可版本控制的文本图表。Mermaid 是什么让文档跟上代码演进Mermaid lets you create diagrams and visualizations using text and code.这是 Mermaid 官网首页源码版见此处阅读版见 docs/intro/index.md的第一句话也是它区别于传统拖拽式画图工具的核心定位图表以文本形式存在、随代码一并纳入版本管理。Mermaid 是一个 JavaScript 图表工具它读取受 Markdown 启发的文本定义再由渲染器把文本翻译成复杂图表并支持在运行时动态创建与修改。它遵循的语法风格与 Markdown 高度一致——如果你熟悉 Markdown几乎可以零成本迁移到 Mermaid 语法参考。它要解决的核心痛点Doc-RotMermaid 的创造者 Knut Sveidqvist 在文档中直言Doc-Rot is a Catch-22 that Mermaid helps to solve.文档腐化是一个让 Mermaid 帮助解决的第 22 条军规式困境。绘图和文档写作会消耗宝贵的开发者时间而且极易过时但如果没有图表与文档又会导致生产力下降、组织知识无法沉淀。Mermaid 的解法是让图表可以像代码一样被快速修改并可以被纳入生产脚本或其它代码片段中使图例与代码天然同步演进真正达成帮助文档跟上开发help documentation catch up with development这一主目标。Mermaid 通过 Mermaid Live Editor官方在线编辑器的入门章节让非程序员也能轻松创建精细图表在 GitHub、GitLab 等支持 Markdown 的应用中可以直接书写mermaid代码块来内嵌图表想要把图表嵌入自己的站点或应用则可查阅 Mermaid 集成清单。部署、语法、配置三大部分Mermaid 的整体使用可拆分为三大支柱见 入门指南Deployment部署——如何在 Live Editor、网页 API、包依赖等场景运行 MermaidSyntax语法——如何用文本描述各类图表Configuration配置——如何通过initialize/mermaidAPI与各类配置项控制渲染外观与行为。覆盖的图表类型仓库 READMEREADME.md与本仓库demos/目录共同印证了 Mermaid 的能力范围远超流程图本身源码侧对应实现位于 packages/mermaid/src常见类型包括流程图flowchart语法见 docs/syntax/flowchart.md、时序图sequenceDiagramdocs/syntax/sequenceDiagram.md类图classDiagramdocs/syntax/classDiagram.md、状态图stateDiagramdocs/syntax/stateDiagram.mdER 实体关系图docs/syntax/entityRelationshipDiagram.md、C4 架构图docs/syntax/c4.md甘特图gantt、饼图pie、Git 提交图gitGraph、思维导图mindmap、时序时间线timeline、桑基图sankey等 20 余种每种图表的可视化验证用例集中在仓库 e2e/diagrams 下如e2e/diagrams/flowchart、e2e/diagrams/class-diagram中成百上千个.mmd快照用例而交互式演示页统一收录于 demos/index.html可直接在浏览器中打开体验每种语法。安装 MermaidCDN 与包管理器两种路径官方文档index.md 安装章节提供了两种主流安装方式。通过 CDN 引入无构建工具以 jsDelivr 等 CDN 为例其目录结构形如CDN_URL/mermaidversion/dist/把version替换为目标版本号即可精确锁定版本。本仓库packages/mermaid/package.json当前标注的发布版本为11.17.0产物目录即dist/由 esbuild 构建生成入口源码见 packages/mermaid/src/mermaid.ts。通过包管理器安装到项目中如果项目本身使用 Node.js 生态可把 Mermaid 作为运行时依赖加入package.jsonNPMnpm i mermaidYarnyarn add mermaidPnpmpnpm add mermaid官方文档在部署一节对 Node.js 环境给出的最低建议为 Node v16自带 npm而更晚近的 docs/intro/getting-started.md 已推荐Node.js v20 或更高建议 LTS。若希望仅作为开发期工具可追加--save-dev/--dev标记写入 devDependencies。关于引入后的详细用法官方推荐继续阅读 docs/intro/getting-started.md 与 docs/config/usage.md。无需打包器部署Mermaid JavaScript API官方提供的最小化部署方案不需要 webpack、Vite 等任何打包器只需在一个 HTML 页面中做两件事在页面中放置带有classmermaid的div或pre容器里面书写图表的文本定义用script typemodule导入 Mermaid 的 ESM 产物并调用mermaid.initialize(...)完成初始化与启动渲染。最小示例script typemodule import mermaid from CDN_URL/mermaidversion/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /scriptmermaid.initialize({ startOnLoad: true })的作用是命令 Mermaid 解析器去扫描页面中所有classmermaid的div或pre标签读取其中的图表/图表定义文本并将它们渲染为SVG 图表注意每个图表应放在独立的标签中。完整 HTML 页面示例可参考 docs/config/usage.md 中的内嵌演示更多渲染样例见 docs/syntax/examples.md。startOnLoad与页面生命周期startOnLoad是initialize中最常用的一个参数参数说明类型取值startOnLoad页面加载完成后是否立即开始渲染Booleantrue/false从源码看packages/mermaid/src/mermaid.tsmermaid.initialize(config)会把配置透传给内部mermaidAPI.initialize随后模块在window上注册load事件监听页面加载完成后调用contentLoaded若检测到startOnLoad为真即执行mermaid.run()开始渲染。将startOnLoad设为false则能手动控制扫描pre classmermaid的时机——当页面中部分标签可能在 ESM 脚本执行后才注入 DOM 时这一开关尤其有用。手动控制渲染run、parse与rendermermaid.initialize()只是注册 配置真正干活的是run。源码中 run 的实现 逻辑清晰可读默认使用querySelector: .mermaid查找待渲染节点对每个元素检查data-processed属性已处理过的节点会被跳过因此initialize/run可被多次安全触发读取元素内文本并做实体解码、缩进规整dedent等预处理依次调用render(id, text, element)生成 SVG 并回写innerHTML随后执行可选的postRenderCallback与bindFunctions用于把点击事件等交互能力绑定回 DOM。如果要在任意 HTML 容器中按需渲染一段字符串可直接使用mermaid.render(id, text)——它以 Promise 形式返回{ svg, bindFunctions }多个并发调用会被放入内部执行队列串行处理。而在提交渲染前还可以调用mermaid.parse(text)先行校验语法配合{ suppressErrors: true }可以返回false而非抛错。使用 Mermaid 的五种途径总览综合 入门指南 与 index.md可以把 Mermaid 的使用场景归纳为五类Mermaid Live Editor直接在浏览器中编辑Code面板并即时预览支持导出 PNG / SVG / Markdown、从 Gist 加载要求包含code.mmd与可选的config.json、本地历史自动保存编辑历史存于浏览器存储Mermaid Chart Editor / Mermaid Chart 服务面向团队协作、AI 绘图与多用户编辑的官方 Web 编辑器对应生态文档见 docs/ecosystem/mermaid-chart.md第三方插件与集成将图表能力嵌入 ChatGPT、JetBrains IDE、VS Code、Microsoft Word/PowerPoint 等工具清单见 docs/ecosystem/integrations-community.md原生 Markdown 环境GitHub、GitLab 等支持 Markdown 的平台可直接书写mermaid代码块调用 JavaScript API / 加入依赖即上文介绍的 ESM 引入、initializerun、或将mermaid作为 npm 依赖交给任意构建工具处理。对第 5 种场景官方还在 docs/intro/getting-started.md 中给出了把 mermaid 文件置于项目本地并用相对路径引用mermaid.esm.mjs的示例——这意味着不依赖公共 CDN、离线内网部署同样可行只需把引入地址从 CDN 改为./node_modules/...对应的 dist 产物路径即可。安全渲染从净化到沙箱Mermaid 图表语法中包含大量与 HTML 冲突的特殊字符标准的 HTML 消毒方案sanitizer在过滤危险脚本的同时极易破坏图表本身。对此官方在 安全文档 中明确了多层防护策略。内建净化DOMPurify默认情况下Mermaid 使用一套基线 [DOMPurify] 配置对输入代码做净化处理。如果你清楚风险可以在 Mermaid 配置中加入dompurifyConfig键覆盖传给 DOMPurify 的选项——但官方明确警告错误覆盖可能破坏 Mermaid 输出务必谨慎。securityLevel 安全等级从 config.type.ts 配置类型定义 可以看到securityLevel存在四种取值取值语义strict严格模式禁用点击事件等交互能力例如节点/任务的 click 绑定仅在loose下启用见 docs/syntax/flowchart.md 相关说明loose宽松模式允许 JavaScript 回调等交互能力antiscript反脚本模式阻止脚本执行sandbox沙箱模式图表在沙箱化 iframe中渲染禁止代码中的 JavaScript 被执行其中sandbox是针对公网站点接收陌生用户文本场景引入的更高级别安全选项把渲染隔离在沙箱 iframe 内即便输入内容存在恶意脚本也无法在宿主页面执行是无法绝对保证消毒无漏洞前提下的一大进步。官方同时坦诚其代价——Unfortunately you cannot have a cake and eat it at the same time在阻断恶意代码的同时部分交互功能也会一并失效。相关净化与 XSS 防护在仓库内由 e2e/other/xss.spec.js 等测试持续守护。漏洞报告渠道如果发现安全漏洞官方要求通过邮件 securitymermaid.live 提交邮件中需包含问题描述、复现步骤、受影响版本以及已知的缓解措施预期在三个工作日内获得回复。完整流程与依赖更新建议见 docs/community/security.md。周边生态官方 Live Editor、CLI 与兄弟项目Mermaid 的生态在仓库中也有对应落点Mermaid Live Editor官方在线编辑器也是非程序员上手的最快路径仓库内的本地编辑器实现可参考 packages/mermaid-local-editorMermaid CLI命令行渲染工具便于把.mmd文件接入 CI 流水线批量产出图片Mermaid Tiny极简裁剪版实现见 packages/tiny用于对包体积与加载时机敏感的嵌入场景Mermaid Chart 插件面向 ChatGPT、JetBrains、Office 系产品的商业化插件介绍见 docs/ecosystem/mermaid-chart.md教学视频与社区教程集中在 docs/ecosystem/tutorials.md期望自己动手开发一款集成的开发者可先读 docs/ecosystem/integrations-create.md。从源码参与开发环境、测试与发布官方在 index.md 末尾开放了完整的仓库协作指引仓库根 package.json 亦印证了这套脚本体系。本地开发环境要求[volta] 用于管理 Node 版本Node.jsvolta install nodepnpm 包管理器volta install pnpm。本仓库根目录声明的包管理器为pnpm10.30.3属于 pnpm 10.x 系列。开发安装与校验git clone mermaid 仓库地址 cd mermaid # 首次安装需要 npx因为 volta 对 pnpm 的支持尚未内置 npx pnpm install pnpm test后续迭代中常用命令包括pnpm lint # ESLint Prettier jison 语法检查 pnpm test # 根级 vitest 单元测试根目录package.json中实际定义的test脚本为pnpm lint vitest run浏览器端手动验证可先执行构建产物再打开packages/mermaid/dist下的本地编辑器页根脚本中亦封装了pnpm serve:dist等辅助命令。单元测试与 e2e 用例遍布 packages/mermaid/src 与 e2e 目录新增图表类型或修改渲染逻辑时均有对应快照回归保护。发布流程对具备发布权限的维护者官方流程为先在package.json中更新版本号随后执行npm publish——该命令会把构建产物生成到dist/目录并发布至 npm。详细贡献规范含编码风格、PR 流程、编辑器插件建议见 docs/community/contributing.md。快速动手建议若想以最短路径获得文本即图表的实战体验可以按此顺序推进打开 demos/index.html 挑选感兴趣的图表类型对照demos/下各类.html页面内的源码文本查阅对应语法文档如 docs/syntax/flowchart.md在 Mermaid Live Editor 或本地 HTML 中修改验证将验证通过的.mmd文本沉淀到项目的docs/或 Markdown 文档中让图表随代码一起提交、Review、回溯——这正是 Mermaid 对抗文档腐化的日常用法。综上Mermaid 把图表从一次性产物转变为可复用的文本资产前端工程、静态站点、知识库乃至生产脚本都能借助它实现低成本的动态图表化表达。掌握本文的安装、API 部署、安全等级与配置要点后即可根据自身场景在五类使用途径间自由切换。【免费下载链接】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），仅供参考
