Diagram source that gets reviewed like code
Mermaid is a JavaScript library that takes a diagram written as Markdown-like text and draws it as SVG. The README names its target: doc rot. Diagrams eat developer time and go stale fast, yet a team without them loses productivity and shared knowledge. Mermaid's answer is to do without a design tool or a drag-and-drop canvas. Since the diagram is text, it changes in the same commit as the code it describes and shows up in a pull request as an ordinary diff.
Native rendering on GitHub, GitLab, Notion and Obsidian
- A fenced
mermaidblock renders as a diagram on GitHub, GitLab, Gitea, Forgejo and Azure DevOps, and in Notion, Obsidian and Joplin, according to the project's integration list. VS Code and JetBrains IDEs need an extension. - Over twenty diagram types, among them flowcharts, sequence, class, state, ER, Gantt, git graphs, mindmaps, timelines, Sankey and C4. UML use case diagrams arrived in 12.0.0.
- The live editor at mermaid.live shows the result as the text changes, which is where the syntax gets debugged before it goes into a doc.
- In a web page, the npm package or the jsDelivr CDN does the rendering. At build time, the
mmdcCLI writes SVG, PNG or PDF files, and it also ships as a Docker image. - Other tools read the syntax: Excalidraw turns a Mermaid definition into a drawing that can then be edited by hand.
Rendering in a browser, untrusted input and the 12.0 break
Mermaid only draws inside a browser. The 12.0.0 release notes say so outright. To get an image outside a web page, the mmdc CLI starts a headless Chromium through Puppeteer and requires Node 22.13 or later.
Diagram text written by strangers is an attack surface. The README warns that the syntax uses too many HTML characters for standard sanitizing, and that the team cannot guarantee there are no loopholes. The default strict security level encodes HTML tags and disables click handlers. The sandbox level, still in beta, renders inside an isolated iframe and blocks part of the diagram's interactivity. The repository published nine security advisories in 2026 (CSS and HTML injection, denial of service, prototype pollution), after two critical XSS flaws in August 2025.
Version 12 redraws diagrams nobody edited. Released on 10 September 2026, 12.0.0 is a breaking release: it targets ES2024 and needs Safari 17.4 and Node 22.12 or newer. ELK replaces dagre as the layout engine, and the redux-color theme with the neo look replaces default and classic for most diagram types, so a diagram without configuration moves around and changes colour. mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' }) restores the old rendering. The single-file mermaid.min.js build inlines ELK and grew by roughly 500 kB gzipped, while the tiny build leaves ELK out.
The official docs sit on a commercial site. They are served from mermaid.ai, where the team behind Mermaid also sells an online service with AI diagram generation, real-time co-editing and SSO. The library itself remains MIT-licensed.
The latest release is 12.2.0, from 13 October 2026. It follows 12.1.0 from 2 October, and the last commit landed on 27 October 2026.