If you write code for a living, you've probably needed to explain how a system works to a teammate, a new hire, or even yourself six months later. Diagrams help, but switching to a drawing tool breaks your flow. Mermaid solves this by letting you write diagrams using a simple text-based syntax right inside your markdown files, documentation repos, and even pull requests. This reference covers the syntax you'll actually use day to day as a developer.

What is Mermaid, and why should developers care about it?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from text written in a markdown-like syntax. Instead of dragging shapes around in a GUI, you write a few lines of plain text and get a clean diagram. It was created by Knut Sveidqvist and is now maintained as an open-source project with an active community.

Developers use Mermaid because it lives inside their existing workflow. GitHub, GitLab, Bitbucket, and many documentation platforms render Mermaid blocks natively. That means your diagrams live in version control alongside your code. No more stale screenshots in a wiki nobody updates. If you want to see how this works in real documentation contexts, check out these practical code examples for software documentation.

The official Mermaid.js documentation covers every feature in depth, but what follows is the syntax you'll reach for most often.

How do you write a flowchart in Mermaid?

Flowcharts are the most common Mermaid diagram. You define nodes and connect them with arrows. Here's the basic structure:

Node shapes are defined by the brackets you use:

• Rectangle: id[Text]
• Rounded rectangle: id(Text)
• Circle: id((Text))
• Rhombus (decision): id{Text}
• Parallelogram: id[/Text/]
• Hexagon: id{{Text}}

Connections use arrows between node IDs:

• A --> B arrow with no label
• A -->|Yes| B arrow with label
• A --- B line without arrowhead
• A -.-> B dotted arrow
• A ==> B thick arrow

A simple example:

flowchart TD
A[User visits login] --> B{Credentials valid?}
B -->|Yes| C[Dashboard]
B -->|No| D[Error message]
D --> A

The direction keyword after flowchart sets the layout: TD (top-down), LR (left-right), BT (bottom-top), or RL (right-left). Use LR when your process reads naturally left to right, which often works better for wider screens.

How do sequence diagrams work in Mermaid?

Sequence diagrams show interactions between actors or services over time. They're useful for API flows, authentication sequences, and any multi-service communication. The syntax is straightforward:

sequenceDiagram
participant Client
participant API
participant DB
Client->>API: POST /login
API->>DB: Query user
DB-->>API: User record
API-->>Client: 200 OK + token

Arrow types matter here:

• ->> solid line with open arrowhead (synchronous call)
• -->> dashed line with open arrowhead (response)
• ->>x solid line ending with an X (async message that fails)

You can also add loops, conditions, and notes using keywords like loop, alt, opt, and Note. For a deeper walkthrough of these features, the sequence diagram guide for beginners covers each construct with real examples.

What about class diagrams and ER diagrams?

Class diagrams use the classDiagram keyword and let you model object relationships:

classDiagram
class User {
+String name
+String email
+login()
}
class Order {
+Date createdAt
+Float total
}
User "1" --> "" Order : places

Entity-relationship diagrams use the erDiagram keyword for database schema visualization:

erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains

The relationship symbols follow standard crow's foot notation: || means exactly one, |o means zero or one, }o means zero or many, and |{ means one or many.

Which diagram types does Mermaid support?

Mermaid supports a growing list of diagram types. The ones developers use most:

• Flowchart process flows, architecture overviews, decision trees
• Sequence diagram API interactions, message flows between services
• Class diagram object-oriented design, data model relationships
• ER diagram database schema design
• State diagram finite state machines, UI state transitions
• Gantt chart project timelines and sprint planning
• Pie chart simple proportional data
• Git graph branch and merge visualization
• Mindmap brainstorming and hierarchical ideas
• Timeline chronological events
• Quadrant chart 2x2 matrix comparisons
• Sankey diagram flow quantities between stages

Each diagram type starts with its own keyword flowchart, sequenceDiagram, classDiagram, erDiagram, stateDiagram-v2, gantt, pie, gitGraph, mindmap, timeline, quadrantChart, and sankey-beta.

How do you add Mermaid diagrams to GitHub and GitLab?

Both GitHub and GitLab render Mermaid natively. Wrap your diagram in a fenced code block with the mermaid language identifier:

```mermaid
flowchart LR
A[Start] --> B[End]
```

This works in README files, issues, pull request descriptions, wikis, and comments. No plugins or extensions needed. If you're building a documentation site, tools like Docusaurus, MkDocs with plugins, and VitePress all support Mermaid rendering out of the box or with minimal config.

What are the most common mistakes developers make with Mermaid syntax?

After helping teams adopt Mermaid, these errors come up again and again:

• Missing the direction keyword. Writing flowchart without TD or LR causes rendering issues in some parsers. Always include a direction.
• Special characters in node text. Parentheses, brackets, and quotes inside labels break the parser. Use quotes around the text: A["User (admin)"].
• Inconsistent indentation. Mermaid is somewhat forgiving, but mixing tabs and spaces can cause problems in some renderers. Stick with spaces.
• Forgetting subgraph syntax. Grouping nodes requires the subgraph keyword with a matching end. The subgraph title goes on the same line: subgraph "Authentication Service".
• Using the wrong arrow syntax for diagram types. Sequence diagrams use ->> while flowcharts use -->. Mixing them up produces errors or unexpected output.
• Not quoting labels with special characters. If your node text contains (, [, {, or #, wrap the text in quotes: A["Results #1"].

How do you style Mermaid diagrams with themes and custom CSS?

Mermaid has built-in themes you set with an %%{init}%% directive at the top of your diagram:

%%{init: {'theme': 'dark'}}%%
flowchart TD
A --> B

Available themes: default, forest, dark, neutral, and base. You can also customize individual elements with the style keyword:

style A fill:#f9f,stroke:#333,stroke-width:2px

For class and flowchart diagrams, you can apply CSS-like styling to entire node classes using classDef:

classDef error fill:#fee,stroke:#f33
class D,E error

This is useful for color-coding warning states, highlighting critical paths, or matching your company's design system in documentation.

Where can you preview and test Mermaid diagrams before committing?

The fastest way to test a diagram is the Mermaid Live Editor. It renders your diagram in real time and lets you export as SVG or PNG. You can also share diagrams via URL since the diagram code is encoded in the link.

If you work in VS Code, the "Mermaid Markdown Syntax Highlighting" extension provides syntax highlighting inside fenced code blocks, and "Mermaid Preview" renders diagrams in a side panel. JetBrains IDEs have similar plugin support.

For a quick refresher on syntax while you work, keep the Mermaid syntax cheatsheet open in a browser tab. It covers the most-used constructs across all diagram types.

Practical checklist: Getting started with Mermaid today

1. Pick one diagram type you need right now flowchart, sequence diagram, or ER diagram are good starting points.
2. Write the diagram in the Mermaid Live Editor at mermaid.live to get instant feedback.
3. Add it to your project inside a markdown file using a fenced code block with the mermaid language tag.
4. Push to GitHub or GitLab and verify it renders correctly in the repository view.
5. Share the rendered diagram with your team in a pull request or issue instead of a screenshot.
6. Keep the cheatsheet handy memorizing every syntax rule isn't necessary when you have a quick reference nearby.

Start small. One diagram in your next PR is enough to see the value. Once your team notices diagrams living alongside code and staying current, they'll start adding their own.