What is Mermaid? Diagram-as-code explained

Mermaid is an open-source JavaScript library that turns plain text into diagrams. Instead of dragging shapes around a canvas, you describe your diagram in a simple text syntax and Mermaid renders it instantly. This approach – often called diagram-as-code – keeps your diagrams in version control alongside your code and makes them trivial to update.

How Mermaid works

Mermaid parses a lightweight text definition and produces an SVG diagram in the browser. You write a few lines of text, and Mermaid figures out the layout, spacing, and styling automatically.

For example, a three-step flowchart looks like this:

graph LR
    A[Write code] --> B[Push to GitHub]
    B --> C[Deploy]

A simple left-to-right flowchart in Mermaid syntax

Diagram types Mermaid supports

Mermaid covers the most common diagram types developers need:

Flowcharts

Use graph TD (top-down) or graph LR (left-right) to build process flows, decision trees, and system architecture diagrams. Nodes can be rectangles, rounded rectangles, diamonds (decisions), cylinders (databases), or circles.

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug it]
    D --> B

Sequence diagrams

Sequence diagrams model interactions between actors over time. They are ideal for documenting API flows, authentication sequences, and microservice communication.

sequenceDiagram
    Browser->>Server: GET /api/data
    Server->>Database: SELECT * FROM items
    Database-->>Server: rows
    Server-->>Browser: 200 OK

Entity-relationship (ER) diagrams

ER diagrams describe the tables in a database and how they relate. Mermaid's erDiagram syntax supports cardinality notation and inline attribute definitions.

Gantt charts

Gantt charts show project timelines with sections, tasks, durations, and dependencies. They are useful for sprint plans, product launch roadmaps, and release schedules.

Other types

Mermaid also supports class diagrams (UML), mind maps, pie charts, state diagrams, and more. The full list continues to grow with each release.

Why developers use Mermaid

Drawing tools like Lucidchart or draw.io are great, but they produce binary files that are hard to diff and review in pull requests. Mermaid diagrams live in plain text, so they travel well:

Version control – commit your diagrams alongside your code and track every change in Git.

Documentation sites – GitHub, GitLab, Notion, and many wikis render Mermaid natively inside Markdown fenced code blocks.

Speed – updating a diagram means editing a line of text, not re-arranging shapes.

Portability – export to SVG or PNG any time, with no vendor lock-in.

How to get started with Mermaid

The fastest way to try Mermaid is to open a live editor in your browser – no installation needed. Diagram.RS is a free, privacy-friendly Mermaid editor: paste or type any Mermaid syntax on the left and see the diagram update in real time on the right.

You can also embed Mermaid in your own project by including the mermaid npm package, or use a fenced code block in GitHub-flavored Markdown – GitHub renders Mermaid automatically.

What is Mermaid? A beginner's guide to diagram-as-code