Mermaid Diagrams in Markdown: A Visual Guide

Mermaid diagrams in markdown let you create flowcharts, sequence diagrams, Gantt charts, and more than 20 other diagram types using nothing but text. Instead of dragging boxes around in a drawing tool, you describe the diagram in a simple syntax inside a fenced code block, and the rendering engine turns it into a visual graphic. Mermaid has over 85,000 GitHub stars and 1.2 million weekly npm downloads, making it the most popular text-to-diagram tool in the developer ecosystem. And because it lives inside markdown, it works naturally alongside your other content: headings, paragraphs, tables, and code.

If you are already familiar with what markdown is and why every AI tool uses it, Mermaid is the natural extension for visual content. Where markdown handles text, Mermaid handles diagrams.

What are Mermaid diagrams and why they matter for markdown

Mermaid is a JavaScript library (currently at v11.x) that parses a text-based domain-specific language and renders it as SVG graphics. You write diagram definitions inside fenced code blocks with the mermaid language identifier:

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

The name "Mermaid" was chosen because the project renders "mer-maid" (markup-aided) diagrams. The syntax is intentionally readable: A --> B means "A points to B." You do not need to know JavaScript, SVG, or any graphics programming to use it.

Why Mermaid matters for markdown specifically:

1. Diagrams live with the content. Instead of maintaining separate diagram files in Figma or draw.io, the diagram definition is part of the same markdown document. When you update the text, you update the diagram.
2. Version control works. Because Mermaid diagrams are text, they diff cleanly in Git. You can see exactly what changed in a pull request.
3. No export/import cycle. Traditional diagramming requires creating a diagram in one tool, exporting it as an image, and embedding the image in your document. Mermaid eliminates all three steps.
4. AI tools can generate them. Ask ChatGPT or Claude to "create a flowchart showing the user registration process" and you get valid Mermaid syntax that renders immediately.

Where Mermaid diagrams work: platform support

Not every markdown processor supports Mermaid. Here is where you can use Mermaid diagrams today:

For platforms that do not support Mermaid natively, you can use the Mermaid Live Editor to render your diagram, export it as SVG or PNG, and embed the image in your document. But wherever possible, keeping the text definition in your markdown is the better long-term approach.

Mermaid flowchart diagrams

Flowcharts are the most common Mermaid diagram type. They show processes, decisions, and connections between steps.

Basic flowchart syntax

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

The key syntax elements:

• graph TD sets the direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
• A[Text] creates a rectangular node
• A{Text} creates a diamond (decision) node
• A(Text) creates a rounded rectangle
• A([Text]) creates a stadium-shaped node
• A[[Text]] creates a subroutine node
• --> creates an arrow
• -->|label| creates a labeled arrow
• --- creates a line without an arrow

Practical flowchart: document publishing workflow

```mermaid
graph LR
    A[Write Markdown] --> B[Choose Template]
    B --> C{Destination?}
    C -->|Web| D[Publish Page]
    C -->|Docs| E[Copy to Google Docs]
    C -->|Team| F[Paste in Slack]
    D --> G[Share URL]
    E --> G
    F --> G
```

Flowchart with subgraphs

Subgraphs group related nodes together:

```mermaid
graph TB
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        C[Express Server] --> D[Database]
        C --> E[Cache]
    end
    B --> C
```

Mermaid v11 supports over 30 node shapes, including cylinders for databases, hexagons, parallelograms, and trapezoids. The full reference is available in the Mermaid documentation.

Mermaid sequence diagrams

Sequence diagrams show how components interact over time. They are essential for documenting APIs, microservice communication, and user flows.

```mermaid
sequenceDiagram
    participant User
    participant App
    participant API
    participant DB

    User->>App: Click "Save"
    App->>API: POST /documents
    API->>DB: INSERT document
    DB-->>API: Success
    API-->>App: 201 Created
    App-->>User: Show confirmation

    Note over App,API: Auto-save triggers every 30s
```

Key syntax elements for sequence diagrams:

• participant Name declares an actor (appears as a box at the top)
• ->> solid arrow with arrowhead (synchronous message)
• -->> dashed arrow with arrowhead (response/return)
• ->>+ activates the target (shows an activation bar)
• ->>- deactivates the source
• Note over A,B: text adds a note spanning participants
• alt / else / end for conditional branches
• loop / end for repeated interactions

Sequence diagram with alternatives and loops

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Cache

    Client->>Server: GET /data
    Server->>Cache: Check cache

    alt Cache hit
        Cache-->>Server: Return cached data
        Server-->>Client: 200 OK (cached)
    else Cache miss
        Server->>Server: Compute result
        Server->>Cache: Store in cache
        Server-->>Client: 200 OK (fresh)
    end
```

Mermaid Gantt charts and timelines

Gantt charts visualize project schedules with tasks, durations, and dependencies.

```mermaid
gantt
    title Product Launch Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Market research       :done, p1, 2026-01-06, 2026-01-17
        Feature specification :done, p2, 2026-01-13, 2026-01-24
        Design mockups        :done, p3, after p2, 10d
    section Development
        Backend API           :active, d1, 2026-02-03, 30d
        Frontend UI           :d2, after d1, 20d
        Integration testing   :d3, after d2, 10d
    section Launch
        Beta release          :milestone, m1, after d3, 0d
        Marketing campaign    :l1, after d3, 14d
        Public launch         :milestone, m2, after l1, 0d
```

Gantt chart syntax:

• title sets the chart title
• dateFormat defines how dates are parsed
• section groups tasks into categories
• Task states: done, active, crit (critical path)
• milestone creates a diamond marker
• after taskId creates a dependency
• Duration: 10d (days), or explicit date range

Timeline diagrams

Mermaid also supports dedicated timeline diagrams for simpler chronological views:

```mermaid
timeline
    title Company History
    2020 : Founded
         : First prototype
    2021 : Seed funding
         : 10 employees
    2022 : Series A
         : Product launch
    2023 : 100K users
         : International expansion
    2024 : Series B
         : 500K users
```

All 20+ Mermaid diagram types

Mermaid supports a wide range of diagram types beyond flowcharts and sequence diagrams. Here is the complete reference:

Each diagram type has its own syntax, but they all follow the same pattern: a keyword on the first line, followed by the diagram definition. You can explore all of them in the Mermaid Live Editor at mermaid.live.

Quick examples of less common types

Pie chart:

```mermaid
pie title Traffic Sources
    "Organic Search" : 42
    "Direct" : 28
    "Social Media" : 18
    "Referral" : 12
```

Entity relationship diagram:

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    DOCUMENT ||--o{ VERSION : has
    DOCUMENT }o--|| TEMPLATE : uses
    USER ||--o{ FOLDER : owns
    FOLDER ||--o{ DOCUMENT : contains
```

Mindmap:

```mermaid
mindmap
  root((Markdown))
    Text Formatting
      Bold
      Italic
      Strikethrough
    Structure
      Headings
      Lists
      Tables
    Extensions
      Mermaid Diagrams
      KaTeX Math
      Callouts
    Publishing
      Web pages
      Google Docs
      Slack
```

Publishing Mermaid diagrams beyond your editor

Creating a Mermaid diagram in your local editor is one thing. Getting it into a shareable format that others can actually see is the markdown publishing challenge.

Not every tool that renders Mermaid locally can publish it. The same portability challenge applies to KaTeX math equations, which face similar rendering limitations across platforms. For a reference of all markdown syntax including diagram blocks, see the markdown cheat sheet.

Here are the common approaches:

Static site generators

Jekyll, Hugo, and Astro can render Mermaid diagrams if you add the Mermaid JavaScript library to your site. The diagrams render client-side in the reader's browser.

Image export

The Mermaid Live Editor lets you export diagrams as SVG or PNG. You can then embed these images in any document. The downside: the diagram is no longer editable as text. You lose the "diagrams as code" benefit.

Publishing platforms

Unmarkdown™ renders all 20+ Mermaid diagram types on published pages. The diagrams render client-side with colors that match your chosen template. If you switch templates, the diagram colors adapt automatically. This means a flowchart published with a dark template gets dark-themed colors, while the same flowchart with a light template gets light-themed colors. You can also use Claude's MCP tools to publish documents that contain Mermaid diagrams directly from your AI workflow.

AI-generated diagrams

A particularly powerful workflow: ask Claude or ChatGPT to generate a Mermaid diagram from a description, paste it into your markdown document, and publish it. The entire process from idea to published visual takes under a minute. For example:

"Create a Mermaid sequence diagram showing how OAuth 2.0 authorization code flow works, including the user, client app, authorization server, and resource server."

The AI generates valid Mermaid syntax that you can paste directly into any tool that supports it.

Tips for writing better Mermaid diagrams

After working with thousands of Mermaid diagrams, these patterns consistently produce better results.

Keep node IDs short, labels descriptive

A[User submits form] --> B[Validate input]

is better than:

UserSubmitsForm[User submits form] --> ValidateInput[Validate input]

Short IDs (A, B, C or s1, s2, s3) make the source easier to read. The labels in brackets are what readers see.

Use subgraphs to reduce visual complexity

When a flowchart grows beyond 10-15 nodes, use subgraphs to cluster related nodes. This creates visual hierarchy and makes the diagram scannable.

Choose the right direction

• TD (top-down) works best for hierarchies and sequential processes
• LR (left-right) works best for timelines and pipelines
• RL and BT are rarely the right choice, but can be useful for specific layouts

Test in the Live Editor first

Before embedding a complex diagram in your document, prototype it at mermaid.live. The editor shows errors in real time and lets you iterate quickly.

Handle long labels gracefully

If a node label is very long, it will stretch the diagram. Break long labels across lines using <br/>:

```mermaid
graph TD
    A[Receive customer<br/>support request] --> B[Classify by<br/>priority level]
```

Version your diagrams

Because Mermaid diagrams are plain text, they work naturally with version control. Commit your diagrams alongside your documentation. When you review a pull request, you can see exactly which connections were added, removed, or changed.

Mermaid diagrams and the future of markdown documentation

Mermaid has become to diagrams what markdown became to text: a plain text format that is readable in its source form and beautiful when rendered. The trajectory is clear. More platforms are adding native support every year. AI tools are getting better at generating valid Mermaid syntax. And the library itself continues to add new diagram types.

For anyone writing technical documentation, project plans, or process guides, Mermaid diagrams eliminate the gap between thinking about a process and visualizing it. Combined with a publishing tool that supports all diagram types, you can go from a text description to a published, shareable visual document without ever opening a drawing application.

Related reading

• What is Markdown Publishing? (And Why It Matters in 2026)
• Markdown Templates: What They Are and Why They Matter
• Best Markdown Publishing Tools in 2026
• How to Use Claude's MCP Tools to Publish Documents