Diagrams with Mermaid
By the end of this lesson you'll turn a plain fenced code block into a real diagram — flowcharts, sequence diagrams, Gantt charts, and pie charts — all written as text that GitHub and many docs tools render automatically.
Learn Diagrams with Mermaid in our free Markdown course — an interactive lesson with worked examples, a practice exercise and a quick reference.
Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
What You'll Learn
💡 Real-World Analogy
Mermaid is like describing a map over the phone . Instead of drawing boxes and arrows by hand, you say "Start box, then an arrow to a decision diamond, then a Yes arrow to the dashboard." Mermaid takes that spoken-style description in text and draws the picture for you. Because it's just text, your diagrams live inside the Markdown, get tracked in version control, and update with a simple edit — no graphics editor required.
1. The Mermaid Code Fence
A Mermaid diagram lives in a fenced code block whose info string is mermaid . Inside the fence you write the diagram in Mermaid's text syntax. A renderer that understands Mermaid (GitHub, GitLab, and many documentation tools) replaces the code block with an actual drawing; a plain Markdown viewer just shows the source text.
2. Flowcharts: Nodes and Edges
A flowchart begins with graph and a direction: TD (top-down) or LR (left-to-right). You then declare nodes — an id plus label text — and connect them with edges written as --> . The node id (like A ) is internal; the bracket style sets the shape: A[Box] is a rectangle, A(Round) is rounded, and A {Decision} is a diamond. Add text between pipes to label an arrow: A -->|Yes| B .
- A[Text] — rectangle (the default box)
- A(Text) — rounded rectangle
- A {Text} — diamond (a decision)
- A((Text)) — circle
- A --> B — solid arrow; A -->|label| B — labelled arrow
🎯 Your Turn #1: a two-box flowchart
Fill in the blanks so the program prints a valid two-node flowchart, then run it. Pick TD or LR for the direction.
3. Sequence Diagrams
A sequence diagram shows messages passed between participants over time. Start with sequenceDiagram , declare each participant , then write messages with arrows: -->> for a solid call and -->> with a dashed style for a reply. Time flows downward, so the order of your lines is the order of the conversation.
Time runs top to bottom; each line is one message.
Here's a worked example that prints real Mermaid source for a flowchart. Run it, read each printed line, then paste a real mermaid fence into a GitHub README to watch the boxes and arrows appear.
🎯 Your Turn #2: a decision with branches
Fill in the blanks so the program prints a flowchart with a diamond decision and two labelled arrows. Remember: {braces} make the diamond, |Yes| and |No| label the arrows.
4. Gantt, Class, and Pie Charts
Mermaid does more than flowcharts. A Gantt chart (keyword gantt ) lays out dated tasks on a timeline. A pie chart (keyword pie ) draws labelled slices from numbers. There are also class diagrams ( classDiagram ) for object structure and several others. Each diagram type has its own opening keyword and small syntax, but they all live in the same mermaid fence.
Common Errors (and the fix)
- My diagram shows as code. The info string is wrong or the platform doesn't support Mermaid. Make sure the fence reads mermaid exactly, and test on GitHub.
- Syntax error from Mermaid. A missing direction ( graph TD ) or a stray bracket breaks parsing. Build the diagram up one line at a time in the Mermaid Live Editor.
- My arrow label vanished. Labels go between pipes right after the arrow: A -->|Yes| B , not A --> Yes B .
- Special characters confuse a node. Wrap label text in quotes when it contains characters like ( or : , e.g. A["Start (here)"] .
- Wrong diagram type. Each type needs its own keyword — sequenceDiagram , gantt , pie — on the first line.
📋 Quick Reference — Mermaid
Concept
Syntax
Flowchart start
graph TD (or LR)
Box node
A[Label]
Decision node
A {Label}
Edge
A --> B
Labelled edge
A -->|Yes| B
Sequence
sequenceDiagram
Gantt / Pie
gantt / pie
Mini-Challenge: A Login Flow
No blanks this time — just a brief and an outline. Use console.log to print the source for a flowchart with a start box, a decision diamond, and Yes/No arrows to two outcome boxes. Run it, then wrap it in a mermaid fence on GitHub.
Pro Tips
- 💡 Prototype live. The Mermaid Live Editor renders as you type, so you can fix syntax before pasting into your repo.
- 💡 Keep node ids short. Ids like A , B , C keep edges readable; the visible label goes in the brackets.
- 💡 Switch direction for wide charts. If a top-down chart gets tall, change graph TD to graph LR for a left-to-right flow.
- 💡 Comment with %%. Lines beginning with %% are Mermaid comments and won't render.
Frequently Asked Questions
Q: Does Mermaid work in every Markdown viewer?
No. It renders where it's supported — GitHub, GitLab, Obsidian, and docs tools with a Mermaid plugin. Plain parsers show the fenced code as text.
No. It's an extension layered on top of fenced code blocks. The Markdown itself just sees a code block labelled mermaid ; a separate library does the drawing.
Yes. Mermaid supports themes and per-node styling with classDef and style directives, though the basics in this lesson need none of that.
The Mermaid Live Editor and the Mermaid CLI can export PNG or SVG, which is handy for slides or sites that don't render Mermaid live.
Lesson Complete! 🎉
- ✅ A diagram lives in a fenced code block labelled mermaid
- ✅ Flowcharts start with graph TD , with nodes and --> edges
- ✅ Brackets set node shape: [box] , (round) , {decision}
- ✅ Text between |pipes| labels an arrow
- ✅ Other types include sequence, gantt, class, and pie diagrams
- ✅ It renders on GitHub, GitLab, and many documentation tools
Where to go next: diagrams handle pictures; now handle equations. Continue to Math with LaTeX to write fractions, Greek letters, and integrals inside Markdown.
Practice quiz
How do you embed a Mermaid diagram in Markdown?
- In a fenced code block labelled mermaid
- With an image tag
- Inside a YAML block
- With double brackets
Answer: In a fenced code block labelled mermaid. You write a fenced code block whose info string is mermaid; the renderer turns its contents into a diagram.
Which keyword starts a top-down flowchart?
- diagram down
- chart top
- graph TD
- flow vertical
Answer: graph TD. graph TD (top-down) begins a flowchart; LR gives left-to-right.
What does TD mean in graph TD?
- Two dimensional
- Top Down direction
- Tree Data
- Text Display
Answer: Top Down direction. TD sets the layout direction to top-down; other options include LR, RL, and BT.
How is an edge (arrow) between two nodes written in a flowchart?
- A ~~ B
- A == B
- A :: B
- A --> B
Answer: A --> B. Two nodes are connected with -->, for example A --> B.
How do you give a node square-bracket label text, like a box named Start?
- A{Start}
Square brackets A[Start] create a rectangular node with the text Start.
Which Mermaid diagram type shows messages exchanged over time between participants?
- sequenceDiagram
- pie
- gantt
- classDiagram
Answer: sequenceDiagram. sequenceDiagram models participants and the ordered messages passed between them.
Which keyword begins a Mermaid Gantt chart?
- schedule
- gantt
- calendar
- timeline
Answer: gantt. A Gantt chart starts with the gantt keyword, followed by a title and dated tasks.
Where does Mermaid commonly render automatically?
- Image-only galleries
- Only in PDFs
- Plain text editors with no preview
- GitHub and GitLab Markdown
Answer: GitHub and GitLab Markdown. GitHub and GitLab render mermaid code blocks natively, as do many documentation tools.
What does an arrow label like A -->|Yes| B do?
- Makes the arrow dashed
- Colours the node yellow
- Puts the text Yes on the connecting arrow
- Deletes node B
Answer: Puts the text Yes on the connecting arrow. Text between pipes after the arrow labels that edge; here the arrow reads Yes.
Which shape syntax creates a decision diamond in a flowchart?
- A((round))
Curly braces A{question} produce a diamond, the conventional shape for a decision.
Continue this course
- Previous: YAML Front Matter
- Next: Math with LaTeX