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. Applications can recognize a mermaid fenced code block and run Mermaid on it. This is an application extension, rather than core Markdown syntax:

```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 changes can be reviewed together. The diagram still needs to be checked against the system it describes.
• 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. A Mermaid-aware application can render it, while a plain Markdown renderer may show the 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 may prevent rendering. A typo like flwochart or a missing arrow may produce an error or leave the code visible, depending on the application. 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. error reporting varies by application. Check the syntax against the official Mermaid documentation and reduce the example until the failing line is clear.

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 can check whether the diagram matches the implementation.

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 a broken diagram by reducing it to a small example and checking the official syntax reference.

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