DEV Community

ThatToolSite
ThatToolSite

Posted on Originally published at thattoolsite.com

How to Render Mermaid Diagrams in Markdown

#markdown #documentation #webdev #tutorial

Put the diagram code in a fenced block tagged mermaid. GitHub, GitLab and VS Code draw it; many other places show it as code. Here is how to make it render, and what to do where it can't.

The Mermaid editor draws the diagram as you type, points at the line with an error, and exports PNG or SVG for places that can't render Mermaid. It runs in your browser.

Open the Mermaid editor

How to add a Mermaid diagram to Markdown

Write the diagram code inside a fenced code block and put the word mermaid straight after the opening three backticks. That word is the whole trick: renderers that support Mermaid look for it and draw a diagram instead of showing code.

```mermaid
flowchart TD
    A[Order placed] --> B{Paid?}
    B -- Yes --> C[Ship it]
    B -- No --> D[Send reminder]
```
Enter fullscreen mode Exit fullscreen mode

The first line inside the block names the diagram type: flowchart (or the older graph), sequenceDiagram, classDiagram, gantt, pie, mindmap and others. After it, TD means top to bottom and LR left to right. Square brackets make a box, curly braces a decision diamond, and --> an arrow. Text between -- and the arrow labels it.

Where Mermaid renders, and where it doesn't

Place Renders Mermaid?
GitHub: Markdown files, issues, pull requests, discussions, wikis Yes
GitLab Yes
VS Code's built-in Markdown preview Yes
The Markdown viewer and Markdown to PDF on this site Yes
A GitHub Pages site built with Jekyll Not by itself; the site has to load Mermaid's script
Word, Google Docs, email, most chat apps No; use an exported image

A renderer can also be behind the latest Mermaid release, so a newer diagram type may show an error on one site and work on another. On GitHub, a mermaid block that contains only the word info shows the version in use.

The errors that stop a diagram rendering

Each of these was typed into the Mermaid editor here (Mermaid 12). The left column fails, the right column draws.

Fails Works Why
start --> end start --> End A node called end in lower case ends the flowchart. Capitalise it.
A[Install (v2)] A["Install (v2)"] Brackets inside a label look like shape syntax. Put the label in double quotes.
A —> B A --> B An em dash is not two hyphens. Word processors and some AI answers swap them.
Flowchart TD flowchart TD The diagram type is case-sensitive.
Alice->>Bob: Hi; how are you? Alice->>Bob: Hi #59; how are you? In a sequence diagram a semicolon ends the line. Write it as the code #59;.

Error messages name a line and the token the parser didn't expect. The real mistake is usually on that line or just before it.

Diagrams written by ChatGPT, Claude or Gemini

AI assistants write Mermaid well, but the mistakes above turn up often, especially labels with brackets or colons copied from your own wording. When an answer contains a diagram:

  • Copy only what is inside the fence, or the whole block including the `mermaid line, not the text around it.
  • Paste it into the Mermaid editor first. If it draws there, it's valid Mermaid, and any remaining problem is the renderer's version.
  • Ask the assistant to “quote every node label”. Quoted labels avoid most bracket and punctuation errors.

When the place can't render Mermaid: use an image

For a slide, a Word document or an email, export the diagram. In the Mermaid editor, choose SVG for a sharp vector image that scales to any size, or PNG for apps that don't accept SVG. In a Markdown file on a site without Mermaid support, link the image and keep the source next to it:

`markdown
Order flow

`

Keeping the .mmd source means the next person can change the diagram instead of redrawing it. To check how the whole document looks with the diagram in place, paste it into the Markdown viewer.

Sources

Originally published on ThatToolSite.

Top comments (0)