Mermaid — Generate Diagrams from Text Like Markdown

What Mermaid Does

• Flowcharts — TD, LR, RL, BT directions
• Sequence diagrams — actor interactions with arrows
• Class diagrams — UML-style
• State diagrams — state machine flows
• ER diagrams — entity-relationship
• Gantt charts — project timelines
• Pie charts — data distribution
• Git graphs — branch visualization
• Mindmaps — hierarchical thinking
• Timeline — chronological events
• Quadrant charts — 2x2 matrices
• Block diagrams — architecture views

Architecture

Pure JavaScript/TypeScript library. Parses Mermaid syntax → builds internal graph → renders to SVG via dagre (layout algorithm) and D3 (rendering). Can run in browser, Node.js, or CLI.

Self-Hosting

Client-side library, no backend.

Key Features

• 15+ diagram types
• GitHub Markdown native
• Dark and light themes
• CLI for CI/CD rendering
• Customizable via directives
• Live editor (mermaid.live)
• Plugin for Docusaurus, Obsidian, Notion
• SVG and PNG export
• Accessible (ARIA labels)

Comparison

FAQ

Q: How to use it on GitHub? A: Write a ```mermaid code block directly in a Markdown file and GitHub will render it automatically. No install needed.

Q: Compared to PlantUML? A: Mermaid is pure JS (native to browsers); PlantUML requires a Java backend. Mermaid syntax is more concise; PlantUML has more complete features (stronger activity diagrams).

Q: Can you customize the styling? A: Yes. Use %%{init: {"theme": "forest"}}%% or bind a CSS class. Fully custom theme JSON is also supported.

Sources

• Docs: https://mermaid.js.org/intro
• GitHub: https://github.com/mermaid-js/mermaid
• License: MIT