Does GitHub natively render Mermaid diagrams in Markdown?

Yes! Since 2022 GitHub natively renders Mermaid diagrams inside fenced code blocks tagged with ```mermaid in .md files, Issues, Pull Requests, and Discussions. Our previewer renders with the same Mermaid.js version so you see exactly what GitHub will show.

Can I mix Mermaid diagrams and regular Markdown in one file?

Yes, that is the primary use case. Write your documentation in regular Markdown and embed diagrams anywhere using ```mermaid code blocks. You can also mix LaTeX math equations, GitHub alert callouts, and tables in the same document.

Why does my diagram show "Syntax error" but looks correct?

Common causes: (1) Wrong diagram type keyword — use flowchart not flow. (2) Unquoted labels with special characters — wrap in double quotes. (3) Missing colon in sequenceDiagram participants. (4) Mismatched dateFormat in Gantt charts.

How do I choose between Mermaid and PlantUML?

Mermaid is the better choice for web and GitHub documentation because it renders natively in GitHub Markdown, requires no server-side processing, and has a simpler, more readable text syntax. PlantUML has more advanced UML capabilities but requires a Java server or external image service.

How do I control the direction of a flowchart?

Add the direction after the flowchart keyword: flowchart TD (top-down), flowchart LR (left-right), flowchart RL (right-left), flowchart BT (bottom-top). LR is often the most readable for pipeline and workflow diagrams.

Mermaid.js v10+ Rendering Engine

Mermaid Diagram Preview & Flowchart Tester

Q: Which Mermaid diagram types are supported?

Our previewer supports all major Mermaid v10+ diagram types: flowchart, sequenceDiagram, classDiagram, gitGraph, stateDiagram-v2, gantt, erDiagram, pie, journey, and xychart-beta. We update alongside Mermaid releases.

Real-time Mermaid diagram Markdown viewer and previewer. Write diagram code in Markdown and preview flowcharts, sequence diagrams, class diagrams, Git graphs, and Gantt charts live — exactly as GitHub renders them.

GitHub-CompatibleClient-Side SVG

README.md

Target:

116 words955 chars52 lines4 headings~1 min read

Why diagrams-as-code?

Never Export a Diagram PNG Again

Traditional diagrams — Visio, draw.io, Lucidchart — produce binary files that drift out of sync with your code. Mermaid diagrams live in plain text alongside your documentation, diff cleanly in pull requests, and render natively on GitHub without any image uploads.

Diagrams as Code

Mermaid diagrams are plain text. They live in your repo, get code-reviewed in PRs, and never go stale because they are part of the codebase itself.

Native on GitHub

GitHub has rendered Mermaid natively since May 2022. Your diagrams display in READMEs, Issues, Wikis, and Discussions without any plugins.

Instant Client Render

All rendering happens in your browser using the Mermaid.js SVG engine. No server round-trips, no image hosting — diagrams update as you type.

Complete Mermaid Diagram Types Reference

Copy any snippet into the live editor above to preview the rendered diagram instantly.

Flowchart

Sequence Diagram

API docs

Show communication between participants over time — perfect for API and auth flows.

```mermaid
sequenceDiagram
  participant Browser
  participant Server
  participant DB
  Browser->>Server: GET /api/user
  Server->>DB: SELECT * FROM users
  DB-->>Server: User row
  Server-->>Browser: 200 OK
```

Tips

•Use ->> for solid arrows, -->> for dashed

•Add Note over Participant: text for annotations

•activate/deactivate shows execution span

Class Diagram

OOP design

Model object-oriented relationships, inheritance, and interfaces in code design docs.

```mermaid
classDiagram
  class Animal {
    +String name
    +int age
    +speak() void
  }
  class Dog {
    +fetch() void
  }
  Animal <|-- Dog
```

Tips

•Use <|-- for inheritance, *-- for composition

•Prefix members: + public, - private, # protected

•Add <<interface>> or <<abstract>> stereotypes

Git Graph

Dev workflows

Document branching strategies, release workflows, and git history in your project docs.

```mermaid
gitGraph
  commit id: "Init"
  branch feature
  checkout feature
  commit id: "Add login"
  checkout main
  merge feature id: "Merge"
  commit id: "Release v1.0"
```

Tips

•Use branch <name> to create branches

•Use merge <branch> to merge back

•Add id: "label" to name commits

State Diagram

UI/FSM

Map application states and transitions for UI flows, auth states, and finite state machines.

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Loading : fetch()
  Loading --> Success : data received
  Loading --> Error : request failed
  Error --> Idle : retry
  Success --> [*]
```

Tips

•[*] represents initial and final states

•Add : label on transitions for event names

•Nest states with state S1 { ... }

Gantt Chart

Project planning

Create project timelines, sprint plans, and milestone roadmaps directly in Markdown.

```mermaid
gantt
  title Sprint Planning
  dateFormat YYYY-MM-DD
  section Backend
  API design      :done, 2024-01-01, 3d
  Implementation  :active, 2024-01-04, 5d
  section Frontend
  UI components   :2024-01-03, 4d
```

Tips

•Use done, active, or crit status flags

•dateFormat must match dates used in tasks

•Sections group related tasks visually

Mermaid vs. PlantUML vs. draw.io

Compare diagram tool capabilities to choose the right tool for your documentation workflow.

Feature	Mermaid	PlantUML	draw.io	MarkdownPreview.net
Flowcharts (flowchart TD/LR)				Live SVG render
Sequence Diagrams				Instant preview
Class Diagrams				Full v10 syntax
Git Graphs				Branch history
State Diagrams				v2 syntax
Gantt Charts				Date-format aware
GitHub native rendering				1:1 GitHub output
Live 2-way editing				Markdown + HTML sync
Export clean HTML				One-click copy

Common Mermaid Syntax Errors & Fixes

Most Mermaid render failures trace back to one of these four patterns.

⚠ Missing or wrong diagram type keyword

❌ Wrong

```mermaid
flow TD
  A --> B
```

✅ Correct

```mermaid
flowchart TD
  A --> B
```

The keyword must be exact: flowchart, sequenceDiagram, classDiagram, gitGraph, stateDiagram-v2, gantt, erDiagram.

⚠ Unquoted node labels with special characters

❌ Wrong

A[Hello World (v2)] --> B

✅ Correct

A["Hello World (v2)"] --> B

Node labels containing parentheses, colons, or other special characters must be wrapped in double quotes to avoid parse errors.

⚠ Using HTML entities inside diagrams

❌ Wrong

A["User &amp; Admin"] --> B

✅ Correct

A["User & Admin"] --> B

Do not use HTML entities inside Mermaid diagrams. Write literal characters — entities are treated as literal text.

⚠ Incorrect date format in Gantt charts

❌ Wrong

dateFormat DD/MM/YYYY
Task :2024-01-15, 3d

✅ Correct

dateFormat YYYY-MM-DD
Task :2024-01-15, 3d

The dateFormat declaration must exactly match the date format used in task definitions. Mismatches cause the entire Gantt chart to fail silently.

Frequently Asked Questions

Everything you need to know about Mermaid diagrams in Markdown.

Explore More Markdown Tools

All tools are free, client-side, and require no account.

Live Markdown PreviewerPopular

Full CommonMark editor with real-time HTML preview, Mermaid, KaTeX, and one-click export.

Try it

GitHub Markdown PreviewGFM

Test GitHub READMEs, GFM alerts, task lists, and tables exactly as GitHub renders them.

Try it

LaTeX / KaTeX Math PreviewKaTeX

Inline and block KaTeX equations, matrices, integrals, and aligned math — zero lag.

Try it

Markdown GuidesLearn

Practical tutorials: VS Code preview, GitHub rendering issues, browser workflows, and more.

Try it