Mermaid

Mermaid is a JavaScript library that turns text definitions into diagrams. Instead of drawing boxes in a graphical editor and exporting images, you write a few lines describing nodes, messages, or classes, and Mermaid renders them as SVG. Because diagrams are plain text, they live next to the code and docs they describe, show meaningful diffs in pull requests, and can be updated by anyone who can edit Markdown.

GitHub, GitLab, Azure DevOps, Notion, Obsidian, and documentation generators including Docusaurus, MkDocs, and Sphinx (through extensions) can render Mermaid, which makes it the most widely supported diagrams-as-code format. Its limits are layout control and very large diagrams: Mermaid lays diagrams out automatically, which is fast for small diagrams and frustrating for complex ones.

TL;DR

• Write diagrams as text in fenced mermaid code blocks; platforms render them as SVG.
• Common types: flowchart, sequence, class, state, entity-relationship, Gantt, and architecture diagrams.
• Keep diagrams small and focused — one idea per diagram — and split large systems into several.
• Validate diagrams in CI with mermaid-cli so syntax errors do not reach published docs.
• Add accTitle and accDescr for accessibility, and explain the diagram in surrounding text.
• Use the default strict security level when rendering diagrams from untrusted sources.

Quick Example

A sequence diagram of an OAuth authorization code flow, with accessible title and description:

A flowchart for a deployment pipeline:

Validating every diagram file in CI:

Core Concepts

Diagram Types

Newer diagram types are often marked beta or experimental; check the version your platform renders before relying on them.

Syntax Essentials

• Nodes and shapes in flowcharts: id[Rectangle], id(Rounded), id{Decision}, id[(Database)].
• Edges and labels: A --> B, A -->|label| B, A -.-> B for dotted links.
• Subgraphs group related nodes: subgraph Backend ... end.
• Sequence messages: ->> for calls, -->> for responses, plus alt, opt, loop, and par blocks.
• Comments: lines starting with %%.
• Configuration: a frontmatter block or init directive sets the theme and options per diagram.

Where Diagrams Render

Rendering depends on the Mermaid version each platform bundles, so a diagram that works in the live editor may not render on an older platform version.

Validation and Maintenance

• CI rendering: run mermaid-cli over diagram files (or extracted Markdown blocks) so syntax errors fail the build.
• Visual review: include rendered previews in pull requests for diagram changes.
• Ownership: diagrams in the same directory as the code or ADR they describe are updated alongside it. See Architecture Decision Records.
• Pinned versions: pin the Mermaid version in your docs build so rendering does not change unexpectedly.

Accessibility

Diagrams convey information visually, so they need text alternatives:

• Add accTitle and accDescr — Mermaid emits them as the SVG's accessible title and description.
• Explain the diagram in prose before or after it, covering the key point a reader should take away.
• Do not rely on color alone to distinguish elements; use labels and shapes.
• Check contrast of custom themes in light and dark modes.
• For complex diagrams, provide a table or list with the same information.

See Accessibility.

Security

Mermaid's securityLevel setting controls what diagrams may do. The default, strict, encodes HTML in labels and disables click interactions. loose allows HTML and click handlers, antiscript allows HTML but removes scripts, and sandbox renders inside a sandboxed iframe. If your application renders diagrams written by users — comments, wiki pages, chat — keep strict mode (or sandbox), keep Mermaid updated, and treat diagram text as untrusted input.

Best Practices

One Idea per Diagram

Show one flow, one interaction, or one level of architecture per diagram; split large systems into several small diagrams.

Name Things Consistently

Use the same service and component names in diagrams as in code and docs, so readers can map one to the other.

Prefer Text-Based Diagrams in Repositories

Text diagrams diff, review, and update with the code; reserve image exports for slides and printed material.

Validate and Preview

Render diagrams in CI and in pull request previews, so broken or confusing diagrams are caught before publishing.

Common Mistakes

The Everything Diagram

Diagrams Without Text Alternatives

Loose Security for User Content

FAQ

What is Mermaid used for?

Creating diagrams — flowcharts, sequence diagrams, class and ER diagrams, state machines, Gantt charts, and architecture diagrams — from text definitions that render in Markdown platforms and documentation sites.

Does GitHub support Mermaid?

Yes. GitHub renders fenced code blocks marked mermaid in Markdown files, issues, pull requests, and discussions.

How do I check Mermaid diagrams for errors?

Render them in CI with mermaid-cli, which fails on syntax errors, and preview rendered output in pull requests.

Is Mermaid accessible?

It can be. Use accTitle and accDescr to give the SVG an accessible name and description, explain the diagram in surrounding text, and avoid relying on color alone.

Mermaid or PlantUML?

Mermaid is JavaScript-based and natively supported by many Markdown platforms; PlantUML runs on Java and offers more diagram types and layout control. Mermaid is usually simpler for docs in repositories; PlantUML suits complex UML-heavy documentation.

Related Topics

• Technical Diagrams — Communicating systems visually
• Docs as Code — Managing documentation like software
• Architecture Decision Records — Diagrams alongside decisions
• Accessibility — Making content usable for everyone
• System Design — Designing the systems diagrams describe
• Docusaurus — A docs site generator with Mermaid support

References

• Mermaid documentation
• Accessibility options (Mermaid documentation)
• Usage and security levels (Mermaid documentation)
• mermaid-cli (GitHub)
• Creating diagrams (GitHub Docs)