If you write technical documentation, README files, or wikis, you've probably needed a quick visual diagram without leaving your editor. Mermaid lets you create flowcharts, sequence diagrams, and more using plain text code that renders directly inside markdown. Keeping a cheat sheet nearby saves you from constantly searching for syntax details. This reference covers the most common Mermaid diagram types with copy-paste-ready code examples so you can add diagrams to your markdown documentation fast.

What Is Mermaid and Why Use It in Markdown?

Mermaid is a JavaScript-based diagramming tool that takes text-based code and renders it into diagrams in the browser. It works natively in GitHub, GitLab, Bitbucket, Notion, Obsidian, and many documentation platforms. You write simple code inside a mermaid code fence, and the platform renders the visual for you.

Unlike drag-and-drop diagramming tools, Mermaid diagrams live right inside your markdown files. That means they are version-controlled, diffable, and easy to update. If you've evaluated different diagram-as-code tools for enterprise teams, you'll know Mermaid stands out for its simplicity and wide platform support.

How Do You Write a Mermaid Diagram in Markdown?

Every Mermaid diagram starts with a code fence that declares the language. Here is the basic structure:

```mermaid
graph TD
 A[Start] --> B[End]
```

The keyword after the opening fence tells Mermaid which diagram type to render. The lines below define nodes, connections, labels, and styles. That's all there is to it.

What Are the Most Common Mermaid Diagram Types?

Flowchart (Graph)

Flowcharts are the most popular Mermaid diagram. Use graph or flowchart as the keyword.

```mermaid
graph TD
 A[Login Page] --> B{Valid Credentials?}
 B -->|Yes| C[Dashboard]
 B -->|No| D[Error Message]
 D --> A
```

Direction options:

TD top to bottom
LR left to right
BT bottom to top
RL right to left

Node shapes cheat sheet:

[Text] rectangle
(Text) rounded rectangle
{Text} diamond (decision)
[[Text]] subroutine
[(Text)] cylinder (database)
((Text)) circle
>Text] asymmetric (flag)


Sequence Diagram
Sequence diagrams show interactions between actors or services over time. They are popular in API documentation and system design.
```mermaid
sequenceDiagram
 participant User
 participant API
 participant Database
 User->>API: POST /login
 API->>Database: Query user
 Database-->>API: User record
 API-->>User: 200 OK + token
```

Key syntax notes:

->> solid arrow (request)
-->>  dashed arrow (response)
-x solid arrow with cross (async, lost message)
Use activate and deactivate to show processing bars
Note right of Actor: text adds annotations

For more sequence diagram syntax beyond Mermaid, check out these PlantUML sequence diagram code examples if your project uses PlantUML instead.

Class Diagram
Class diagrams document object-oriented structures. Mermaid supports UML-style class relationships.
```mermaid
classDiagram
 class Animal {
 +String name
 +int age
 +makeSound()
 }
 class Dog {
 +fetch()
 }
 class Cat {
 +purr()
 }
 Animal <|-- Dog
 Animal <|-- Cat
```

Relationship arrows:

<|-- inheritance
-- composition
o-- aggregation
--> association
..> dependency

Visibility markers: + public, - private, # protected, ~ package.

Gantt Chart
Gantt charts visualize project timelines and task schedules.
```mermaid
gantt
 title Sprint 12 Tasks
 dateFormat YYYY-MM-DD
 section Backend
 Design API :a1, 2024-01-01, 5d
 Implement Auth :a2, after a1, 4d
 section Frontend
 Build Login UI :b1, 2024-01-03, 3d
 Connect to API :b2, after a2, 2d
```

Use active, done, or crit after the task ID to style individual tasks differently.

Pie Chart
```mermaid
pie title Bug Distribution by Module
 "Auth" : 35
 "Dashboard" : 25
 "Reports" : 20
 "Other" : 20
```


State Diagram
```mermaid
stateDiagram-v2
 [] --> Idle
 Idle --> Processing : submit
 Processing --> Success : complete
 Processing --> Failed : error
 Failed --> Idle : retry
 Success --> []
```


Entity Relationship Diagram (ERD)
```mermaid
erDiagram
 CUSTOMER ||--o{ ORDER : places
 ORDER ||--|{ LINE_ITEM : contains
 CUSTOMER {
 int id PK
 string name
 string email
 }
 ORDER {
 int id PK
 date created_at
 string status
 }
```


Git Graph
```mermaid
gitGraph
 commit
 commit
 branch develop
 checkout develop
 commit
 commit
 checkout main
 merge develop
 commit
```


How Do You Add Styling and Themes to Mermaid Diagrams?
You can apply CSS-like styles to nodes within your diagram code:
```mermaid
graph LR
 A[Normal] --> B[Styled]
 style B fill:#f96,stroke:#333,stroke-width:2px
 style A fill:#bbf,stroke:#333,color:#fff
```

You can also define reusable classes:
```mermaid
graph LR
 A[API] --> B[DB]
 classDef database fill:#f9f,stroke:#333
 class B database
```

For theme-level changes, Mermaid supports built-in themes: default, forest, dark, and neutral. These are configured in the Mermaid initialization object, which your documentation platform may expose as a setting.

What Common Mistakes Break Mermaid Diagrams?

Missing quotes around special characters. If your node text includes parentheses, brackets, or other punctuation, wrap it in quotes: A["Node (details)"].
Using the wrong arrow syntax. Flowcharts use --> and -->|label|. Sequence diagrams use ->>. Mixing them up means the diagram won't render.
Indentation issues in subgraphs. Nodes inside a subgraph block must be properly indented.
Forgetting the diagram type keyword. Every diagram needs a type declaration on the first line after the code fence: graph TD, sequenceDiagram, classDiagram, etc.
Invisible characters from copy-pasting. Copying code from web pages sometimes inserts zero-width spaces or smart quotes. Paste into a plain text editor first to catch these.


What Tips Make Mermaid Diagrams Easier to Maintain?

Keep node IDs short and meaningful. Use login instead of step_number_three_login_screen. Add descriptive labels inside the brackets.
Use subgraphs to group related nodes. This improves readability in complex flowcharts.
Add comments with %%. Just like code, comments help your future self and teammates understand the diagram logic.
Test on your target platform. Mermaid renders slightly differently on GitHub vs. GitLab vs. Obsidian. Always preview before committing.
Use one diagram per code fence. Don't try to combine multiple diagram types in a single block they won't render.
Version your diagrams alongside code. Since Mermaid lives in markdown files, commit diagram changes in the same PR as the related code changes.


How Does Mermaid Compare to Other Diagram-as-Code Tools?
Mermaid's biggest strength is its native support in documentation platforms. You don't need a separate tool or export step. However, it has limitations with complex layouts, custom graphics, and very large diagrams. Tools like PlantUML and Graphviz offer more control over those edge cases. If your team is evaluating options, this comparison of diagram-as-code tools covers the tradeoffs in detail.

Quick Reference: Mermaid Diagram Keywords

graph / flowchart flowcharts
sequenceDiagram sequence diagrams
classDiagram class diagrams
stateDiagram-v2 state diagrams
erDiagram entity relationship diagrams
gantt Gantt charts
pie pie charts
gitGraph git branch visualizations
journey user journey diagrams
mindmap mind maps

You can always refer back to the official Mermaid documentation for the full syntax reference and live editor.

Your Next Step
Pick one diagram type from this cheat sheet and add it to your next markdown file today. Start with a simple flowchart in your project's README. Once that works, try a sequence diagram for your API docs. Bookmark this page so you have the syntax ready whenever you need it. The best way to learn Mermaid is to use it in real documentation not just reading about it.