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 editorHow 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]
```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
```mermaidline, 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:
<!-- Source: order-flow.mmd. Edit it and export again. -->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
- GitHub Docs: Creating diagrams. Where diagrams render, and the info block
- Mermaid: Flowchart syntax. The lowercase end warning and quoted text
- Visual Studio Code: Markdown. Mermaid in the built-in preview
- GitLab Docs: GitLab Flavored Markdown