How to Draw Diagrams in Markdown with Mermaid

Diagrams make documentation clearer, but image files are painful to maintain: they need a separate editor, binary diffs are unreadable in pull requests, and a tiny label tweak means re-exporting a PNG. Mermaid markdown diagrams solve this by letting you describe a chart as text inside a standard Markdown file. This guide shows you what Mermaid is, which diagram types it supports, and how to render the results in a viewer that understands it.

What Mermaid is

Mermaid is a JavaScript-based diagramming language. Instead of dragging boxes around a canvas, you type short declarations and Mermaid draws the shapes, arrows, and labels for you. Markdown adopted Mermaid as a fenced code block, so a diagram is just:

```mermaid
flowchart LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Do work]
  B -->|No| D[Stop]
```

Because the source is plain text, a Mermaid diagram diffs cleanly in version control, lives next to the prose that explains it, and edits as easily as a code snippet. The diagram is the code.

The whole diagram fits inside a normal ```mermaid fence. No <img> tags, no attached files, no diagram editor required.

Why diagrams-as-code matters

Writing diagrams as text has compounding benefits over time:

• Version control friendly — a label change shows up as a one-line diff instead of a replaced binary blob.
• Text-editable anywhere — fix a typo from your phone, in a terminal, or in the homepage editor without opening dedicated software.
• Single source of truth — the diagram sits in the same .md file as the documentation, so it never drifts out of sync.
• Reusable and scriptable — you can generate diagrams from data or templates the same way you generate any text file.

Supported diagram types

Mermaid covers most of the charts you reach for in technical writing. The declarations are simple enough that you can usually guess the syntax.

Flowchart

A flowchart is the most common Mermaid markdown diagram. LR means left-to-right; TD (top-down) is another common orientation.

```mermaid
flowchart LR
  A[User opens app] --> B[Load profile]
  B --> C{Logged in?}
  C -->|Yes| D[Show dashboard]
  C -->|No| E[Redirect to login]
  E --> D
```

Sequence diagram

Sequence diagrams capture messages between actors over time, perfect for documenting API calls or user journeys.

```mermaid
sequenceDiagram
  participant U as User
  participant W as Web app
  participant A as API
  U->>W: Click "Save"
  W->>A: POST /documents
  A-->>W: 201 Created
  W-->>U: Show success toast
```

Other types you can use

Beyond flowcharts and sequences, Mermaid supports:

• Class diagrams — model object-oriented structures and relationships.
• State diagrams — show transitions between states in a system or process.
• Gantt charts — lay out project tasks along a timeline.
• Pie charts — visualise proportional data with a few lines.
• ER diagrams — describe database tables and their relations.
• Mind maps and user journeys — great for brainstorming and UX flows.

You switch types by changing the first keyword (e.g. stateDiagram-v2, gantt, pie); the rest of the syntax stays declarative.

How to render Mermaid markdown diagrams

Here is the catch: not every Markdown viewer renders Mermaid. GitHub, GitLab, Notion, and a handful of static-site generators do, but many plain viewers just show the raw mermaid code block as text. To see the chart you need a viewer that runs the Mermaid library.

The MD Viewer renders Mermaid markdown diagrams directly in your browser — paste your file and the flowcharts, sequences, and other supported types appear live. You can also iterate on the source in the homepage editor and watch the diagram update as you type, which is much faster than the edit-save-refresh loop of an image-based tool.

Common gotchas

Mermaid is powerful, but its failure modes can be confusing the first time:

• A syntax error renders nothing. A typo like flwochart or a missing arrow often produces a blank diagram with no message. Copy a known-good example, then change one thing at a time.
• Not all viewers support it. As noted above, if you see raw code instead of a chart, open the file in the MD Viewer instead.
• Node labels with special characters — wrap them in quotes (A["Label (note)"]) to avoid parser confusion.
• Indentation is mostly cosmetic but keep it tidy. Mermaid is more forgiving than Python, but consistent indentation makes large diagrams far easier to read and debug.
• Direction goes on the first line. flowchart LR or flowchart TD must come before any nodes.

Tip: when a diagram mysteriously disappears, comment out half of it. Mermaid errors are silent, so bisection is the fastest way to find the offending line.

When to reach for Mermaid

Mermaid shines for documentation that changes often: architecture overviews, onboarding guides, API request flows, decision trees, and project timelines. If a diagram needs to ship once and never move, a polished image is fine. But if it documents a living system — where labels, actors, and steps evolve — keeping it as text pays off every sprint.

A practical workflow: keep one diagrams.md per project, embed several ```mermaid blocks, and render the whole file in the MD Viewer whenever you review changes. Reviewers see clean diffs, and the diagrams always match the code.

Key takeaways

• Mermaid lets you write diagrams as text inside normal Markdown fences.
• Supported types include flowchart, sequence, class, state, Gantt, pie, ER, and more — switch by changing the leading keyword.
• Diagrams-as-code gives you clean version-control diffs, easy editing, and a single source of truth next to your docs.
• Not every viewer renders Mermaid; use a Mermaid-aware viewer to see results.
• Debug silently broken diagrams by bisecting: comment out half and re-render.

Ready to turn your text into charts? Open the MD Viewer, paste a file with a ```mermaid block, and watch your diagrams render live.