Mermaid Diagrams in Markdown: Flowcharts and More

Mermaid markdown lets you create flowcharts, sequence diagrams, Gantt charts, class diagrams, and pie charts using plain text inside fenced code blocks. GitHub renders Mermaid diagrams natively in README files, issues, and pull requests since February 2022. Obsidian, GitLab, and several static site generators also support Mermaid out of the box. This guide covers the syntax for each diagram type with copy-paste examples.

What Is Mermaid in Markdown?

Mermaid is a JavaScript library that converts text-based diagram definitions into SVG graphics. In markdown, you write Mermaid code inside a fenced code block with the mermaid language identifier:

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

The renderer parses this block and replaces it with a visual diagram. No image files, no external tools, no screenshot maintenance. When you update the text, the diagram updates automatically.

Mermaid was created by Knut Sveidqvist in 2014 and has over 70,000 GitHub stars as of April 2026. The library supports 15+ diagram types, though most markdown users rely on the 5 or 6 most common ones covered below.

Flowcharts in Markdown with Mermaid

Flowcharts are the most popular Mermaid diagram type. They show processes, decision trees, and workflows.

Basic flowchart (top to bottom):

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

Direction options: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left).

Node shapes:

Syntax	Shape	Use For
[text]	Rectangle	Process steps
{text}	Diamond	Decisions
(text)	Rounded rectangle	Start/end
((text))	Circle	Connectors
[/text/]	Parallelogram	Input/output

Left-to-right flowchart with styling:

```mermaid
graph LR
    A[User Request] --> B[API Gateway]
    B --> C[Auth Service]
    C --> D{Authenticated?}
    D -->|Yes| E[Process Request]
    D -->|No| F[Return 401]
    E --> G[Return Response]
```

This type of diagram works well for documenting API flows, deployment pipelines, and business processes in README files.

Sequence Diagrams

Sequence diagrams show interactions between components over time. They are common in API documentation and system design documents.

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server
    participant DB

    User->>Browser: Click login
    Browser->>Server: POST /api/login
    Server->>DB: Query user
    DB-->>Server: User data
    Server-->>Browser: JWT token
    Browser-->>User: Redirect to dashboard
```

Arrow types: ->> (solid with arrowhead), -->> (dashed with arrowhead), ->> (solid), -->> (dashed).

You can add notes, loops, and alternative paths:

```mermaid
sequenceDiagram
    Note over User,Server: Authentication Flow
    User->>Server: Login request
    alt Valid credentials
        Server-->>User: 200 OK + token
    else Invalid credentials
        Server-->>User: 401 Unauthorized
    end
```

Gantt Charts

Gantt charts display project timelines and task dependencies. They are useful for project documentation and sprint planning:

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Design
        Wireframes       :a1, 2026-05-01, 7d
        UI Mockups       :a2, after a1, 5d
    section Development
        Frontend         :b1, after a2, 14d
        Backend          :b2, after a2, 14d
        Integration      :b3, after b1, 7d
    section Testing
        QA Testing       :c1, after b3, 7d
        Bug Fixes        :c2, after c1, 5d
```

Gantt syntax supports after references for task dependencies, duration in days (7d), and section grouping for visual organization.

Class Diagrams

Class diagrams document object-oriented code structures. They show classes, properties, methods, and relationships:

```mermaid
classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    class Post {
        +String title
        +String content
        +publish()
    }
    User "1" --> "*" Post : creates
```

Relationship arrows: --> (association), --|> (inheritance), ..|> (implementation), --* (composition), --o (aggregation).

Pie Charts

Pie charts visualize proportional data with minimal syntax:

```mermaid
pie title Website Traffic Sources
    "Organic Search" : 45
    "Direct" : 25
    "Social Media" : 15
    "Referral" : 10
    "Email" : 5
```

Mermaid calculates percentages automatically from the values you provide. Keep pie charts to 5 to 7 slices for readability.

Platform Support for Mermaid Markdown

Platform	Mermaid Support	How to Enable
GitHub	Yes (native)	Works automatically in code blocks since Feb 2022
GitLab	Yes (native)	Works automatically in markdown files
Obsidian	Yes (native)	Works in reading and live preview modes
VS Code	Extension needed	Install Markdown Preview Mermaid Support extension
Hugo	Partial	Requires config and shortcode setup
Jekyll	Plugin needed	Use jekyll-mermaid or include Mermaid JS manually
Notion	No	Not supported
Confluence	Plugin needed	Use the Mermaid plugin from the Atlassian Marketplace

GitHub's native support is the biggest driver of Mermaid adoption. Over 60% of GitHub repositories with diagrams now use Mermaid instead of image files, based on analysis by the Mermaid maintainers.

Common Mistakes with Mermaid Diagrams

Mistake 1: Using the wrong language identifier.

```diagram     (wrong - not recognized)
```mermaid     (correct)

Mistake 2: Special characters in node labels.

Parentheses, brackets, and quotes in node text can break the parser. Wrap problematic labels in double quotes:

graph TD
    A["Process (step 1)"] --> B["Check [status]"]

Mistake 3: Creating overly complex diagrams.

Mermaid works best for diagrams with under 30 nodes. Complex diagrams become unreadable and take seconds to render. Split large diagrams into multiple smaller ones organized by subsystem.

Try Mermaid Syntax in Our Editor

Practice creating diagrams in our editor. Write your Mermaid code in a fenced block and see the result:

Frequently Asked Questions

Summary

Mermaid brings diagrams into your markdown files as code. Flowcharts, sequence diagrams, Gantt charts, and class diagrams all live alongside your text, versioned in Git, and rendered automatically on GitHub, GitLab, and Obsidian. Start with flowcharts using graph TD, keep diagrams under 30 nodes, and use our markdown editor to test your syntax. For a broader overview, check the markdown cheat sheet or learn about markdown code blocks for other fenced block features.

Written by the Markdown Editor Online team. Last updated May 2026.