This document provides a high-level introduction to the Mermaid.js codebase, covering its purpose, architecture, and key subsystems. For detailed information about specific components, see:
Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions into visual diagrams. The main purpose of Mermaid is to help documentation catch up with development, preventing "Doc-Rot" by enabling users to create easily modifiable diagrams that can be version-controlled as text alongside code README.md65-75
The project is distributed as a primary npm package (mermaid) packages/mermaid/package.json2-3 and is accessible via CDN (jsdelivr) README.md18 It supports both browser-based rendering and integration into production scripts README.md75
Sources: README.md65-75 packages/mermaid/package.json2-5
| Feature | Description |
|---|---|
| Text-to-Diagram | Parses Markdown-inspired syntax into SVG diagrams README.md8 |
| 30+ Diagram Types | Flowcharts, sequence, Gantt, class, state, ER, Git graphs, Mindmaps, and more packages/mermaid/package.json16-34 |
| Layout Engines | Dagre (default), ELK (complex graphs), and Tidy-Tree pnpm-lock.yaml81-237 |
| Security Model | DOMPurify sanitization and sandboxed iframe rendering packages/mermaid/package.json83 |
| Theme System | Built-in themes with customizable color schemes via khroma packages/mermaid/package.json86 |
| Plugin Architecture | Support for external diagram definitions like ZenUML packages/mermaid-zenuml/package.json2-4 |
| Live Editor | Real-time preview available at mermaid.live README.md15 |
Sources: README.md4-15 packages/mermaid/package.json16-34 packages/mermaid/package.json71-92 packages/mermaid-zenuml/package.json2-4
Title: Monorepo Package Relationships
The codebase uses pnpm workspaces to manage multiple packages package.json7 The mermaid package at packages/mermaid/ is the core library, which depends on internal packages like @mermaid-js/parser packages/mermaid/package.json73 Specialized layout engines and diagram types are distributed as separate packages within the monorepo pnpm-lock.yaml17-249
Sources: package.json1-7 pnpm-lock.yaml17-249 packages/mermaid/package.json73
Title: Rendering Pipeline to Code Entity Mapping
The rendering pipeline detects the diagram type, fetches the appropriate diagram definition, parses the text, and uses D3-based renderers to generate the final SVG. All output is sanitized via dompurify to prevent XSS packages/mermaid/package.json83
Sources: packages/mermaid/package.json71-92 README.md59-60 packages/mermaid/package.json38-40
| Component | Technology | Purpose |
|---|---|---|
| Build System | esbuild, tsx, TypeScript 5.8 | Bundling and script execution package.json127-165 |
| Parser | Jison, Langium | Grammar-based text parsing package.json145-148 |
| Rendering | d3 7.9, roughjs 4.6 | Visual output and effects packages/mermaid/package.json79-88 |
| Layout | dagre-d3-es 7.0.14, cytoscape | Graph layout algorithms packages/mermaid/package.json76-81 |
| Security | dompurify 3.3, sanitize-url 7.1 | Sanitization packages/mermaid/package.json71-83 |
| Testing | Cypress 14.5, Vitest 3.2 | E2E and unit testing package.json109-120 |
| Documentation | VitePress 1.6, TypeDoc 0.28 | Documentation generation packages/mermaid/package.json126-131 |
Sources: package.json109-165 packages/mermaid/package.json71-131
The codebase supports a wide array of diagram types, each with a dedicated parser and renderer:
| Diagram Type | Syntax Keyword | Use Case |
|---|---|---|
| Flowchart | flowchart, graph | Process flows and logic packages/mermaid/package.json19 |
| Sequence | sequenceDiagram | Interaction between processes docs/syntax/sequenceDiagram.md9-14 |
| Gantt | gantt | Project schedules and timelines packages/mermaid/package.json21 |
| Class | classDiagram | Software structure and relationships packages/mermaid/package.json22 |
| State | stateDiagram | State machine transitions packages/mermaid/package.json4 |
| ER | erDiagram | Database entity relationships packages/mermaid/package.json27 |
| Mindmap | mindmap | Hierarchical brainstorming packages/mermaid/package.json24 |
| Git Graph | gitGraph | Branching and commit history packages/mermaid/package.json23 |
| Quadrant | quadrantChart | Data visualization in four quadrants packages/mermaid/package.json30 |
| Event Modeling | eventModeling | System events and state over time packages/mermaid/package.json33 |
Sources: packages/mermaid/package.json16-34 docs/syntax/sequenceDiagram.md9-14
The project utilizes a robust CI/CD pipeline:
Mermaid implements multiple security layers:
dompurify packages/mermaid/package.json83@braintree/sanitize-url prevents javascript: protocol injections packages/mermaid/package.json71strict, loose, sandbox) control the degree of trust in the input.Sources: README.md59-60 packages/mermaid/package.json71-83
To use Mermaid as a library in your project:
To contribute to the codebase:
For detailed setup instructions, see Installation & Setup.
Sources: package.json17-69 README.md18-19