Back to Blog

Diagrams in Markdown: A Plain-English Guide to Mermaid

November 6, 2026by TypeFire
mermaid diagrammarkdown diagramdiagrams in markdownmermaid markdowndiagram as codewhat is mermaidmermaid tutorialmermaid examples

Most diagrams start in a drawing app and die there. Someone exports a PNG, the process changes, and nobody can find the original file to update it.

Mermaid takes the opposite approach. The diagram is a few lines of text that live in your notes or your repo, right next to the words that explain it, and anyone can change it by editing a line.

The short version

  • Mermaid is text that draws. Write A --> B and you get two boxes and an arrow.
  • It lives in Markdown, inside a code block that starts with ```mermaid.
  • Eight kinds cover most needs: flowchart, sequence, Gantt, mind map, class, ER, state and pie.
  • It draws on GitHub, Obsidian, TypeFire and many docs sites, and stays readable text everywhere else.

What Mermaid looks like

Here's a whole diagram. The first line says what kind it is, and each line after it is one connection.

flowchart LR
  A[Idea] --> B{Worth it?}
  B -- Yes --> C[Draft]
  B -- No --> D[Park it]
  C --> E[Review]
  E --> F[(Ship)]

And here's what any app that understands Mermaid draws from it:

The six lines above, drawn: an idea goes through a decision, then a draft, a review and shipping

That's the whole idea. You never drag a box or line up an arrow. Rename "Review" and the box resizes; add a line and the layout makes room.

How a diagram sits in a Markdown file

A Mermaid diagram goes in a fenced code block with mermaid after the opening backticks:

# Launch plan

Here's how a request moves through the team.

```mermaid
flowchart LR
  A[Request] --> B[Triage] --> C[Build]
```

The rest of your notes carry on below.

Because it's just a code block, the file stays plain Markdown. An app that draws Mermaid shows the picture. An app that doesn't shows the text, which is still easy to read.

The eight kinds worth knowing

Kind First line Use it for Guide
Flowchart flowchart LR Processes and decisions Flowchart syntax
Sequence diagram sequenceDiagram Who talks to whom, in order Sequence syntax
Gantt chart gantt Schedules and plans Gantt syntax
Mind map mindmap Brainstorms and outlines Mind map syntax
Class diagram classDiagram Code structure Class syntax
ER diagram erDiagram Database tables ER syntax
State diagram stateDiagram-v2 Statuses and transitions State syntax
Pie chart pie Shares of a whole Save as an image

Mermaid has more, including timelines, Git graphs, user journeys and quadrant charts, and they work the same way: one keyword, then one line per thing.

Mermaid sequence diagram text becomes a drawn checkout sequence between a customer, a shop and a payments service
A sequence diagram: each line is one message, top to bottom.

Why people write diagrams as text

  • They stay up to date. Editing a word is easier than finding the original drawing file, so people actually do it.
  • They live with the notes. The context stays next to the picture, and searching your notes finds the diagram too.
  • They work in version control. In a repo, a change to a diagram is a one-line diff someone can review.
  • AI can write them. Ask a chat assistant for a diagram and it can answer in Mermaid, which you can draw and fix. More on that in this guide.

Where Mermaid diagrams draw

Where What happens
GitHub and GitLab Draws in READMEs, issues, pull requests and wikis
Obsidian Draws in reading view and live preview
TypeFire (Mac, Chrome, web) Draws as you type, in TypeFire’s colors, with a full-window viewer on the Mac
VS Code Draws in the Markdown preview with a Mermaid extension
Docs sites Many static site tools draw it, sometimes with a plugin
Anywhere else Stays readable text
A Markdown document in TypeFire's editor with Mermaid text on the left and the drawn flowchart on the right
In TypeFire the diagram draws in the note while you type.

Common problems, and the fix

Problem Fix
Nothing draws, you just see code Check the block starts with ```mermaid, all lowercase
A syntax error Usually an unclosed bracket or a typo in an arrow. Fix one line at a time
The diagram is tiny See how to make a Mermaid diagram readable
A label breaks the diagram Put it in quotes: A["Price (USD)"]
You need it as a picture Export as PDF, or save as SVG or PNG (how)

Where to start

Open the free Mermaid live editor in your browser. It starts with an example you can change, draws as you type, and saves in your browser, nothing uploaded. When you want diagrams inside your own notes on a Mac, with zoom, resizing and links to other notes, see diagrams in TypeFire.

In their words

Loved by people who type all day.

Unprompted reactions from users, in their own words.

Exactly what macOS has been needing: blazing fast, beautifully designed, and it respects your privacy without forcing a subscription.
Physician
I use TypeFire every single day, all day long. I love it.
Works at Apple
The way you've handled the AI integrations is very elegant. A great implementation.
Mac user
TypeFire is the absolute replacement for TextExpander.
Works at Apple
I love your app. Love it. The only one that does what I want it to do.
Mac user
I'm loving the date math. Amazing, love it.
ICU doctor
It instantly imported my 502 snippets. Flawless import.
Moved over from TextExpander
Incredibly lightweight. It has quickly become a go-to tool in my daily workflow.
Physician
Love the app, and your development pace rocks.
Longtime user
This app is AWESOME! And I definitely want to buy the Pro version.
Free user
Fantastic. Thank you for the very fast fix.
EU keyboard user
This app has so much potential. I'm really grateful that I found it.
Mac user

Used by people at

AppleRed HatPalo Alto NetworksHubSpotIndeedSentryFreshworksTrustpilotBumbleFarfetchSaint-GobainfoodpandaMcKinseyAccentureIntuitInstacartRakutenDow JonesHearstRokuxAINuroGitGuardianMeltwaterDevRevWoltAirwallex

Company names are places where our users work. They do not imply endorsement or affiliation.