Diagrams with Mermaid

Reviewed & published by Brayan K

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.

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

• Embed a diagram with a fenced code block labelled mermaid
• Build a flowchart with graph TD, nodes, and --> edges
• Shape nodes as boxes [ ], rounds ( ), and decisions { }
• Label arrows with text between |pipes|
• Recognise sequence, gantt, class, and pie diagram types
• Know where Mermaid renders (GitHub, GitLab, docs tools)

💡 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.

\`\`\`mermaid
graph TD
  A[Start] --> B{Logged in?}
  B -->|Yes| C[Show dashboard]
  B -->|No| D[Show login page]
\`\`\`

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.

Node shapes at a glance

• 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.

// 🎯 YOUR TURN — design a tiny flowchart.
// Fill in each ___ then press "Try it Yourself" to print the source.

const direction = "___";   // 👉 TD for top-down, or LR for left-to-right
const firstNode = "___";   // 👉 a label for the start box, e.g. Start
const nextNode  = "___";   // 👉 a label for the next box, e.g. Finish

console.log("graph " + direction);
console.log("  A[" + firstNode + "] --> B[" + nextNode + "]");

// ✅ Expected printed source (example):
//    graph TD
//      A[Start] --> B[Finish]
//
// Wrap it in a mermaid fence on GitHub to see two boxes and an arrow.

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.

\`\`\`mermaid
sequenceDiagram
  participant U as User
  participant S as Server
  U->>S: GET /home
  S-->>U: 200 OK (HTML)
\`\`\`

User ——— GET /home ———▶ Server

User ◀- - 200 OK (HTML) - - Server

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.

## Open a mermaid code fence
(three backticks)mermaid

## A top-down flowchart
graph TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Go]
  B -->|No| A

## Close the fence
(three backticks)

<!-- ✅ Expected result, rendered:
     h2 -> text: Open a mermaid code fence
     h2 -> count: 3
     p  -> count: 3
-->

🎯 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.

// 🎯 YOUR TURN — add a DECISION with two labelled branches.
// A diamond uses {curly braces}; label each arrow between |pipes|.

const question = "___";   // 👉 a yes/no question, e.g. Ready?
const yesPath  = "___";   // 👉 where Yes leads, e.g. Continue
const noPath   = "___";   // 👉 where No leads, e.g. Stop

console.log("graph TD");
console.log("  A{" + question + "}");
console.log("  A -->|Yes| B[" + yesPath + "]");
console.log("  A -->|No| C[" + noPath + "]");

// ✅ Expected printed source (example):
//    graph TD
//      A{Ready?}
//      A -->|Yes| B[Continue]
//      A -->|No| C[Stop]
//
// The {braces} render as a 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.

\`\`\`mermaid
gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Build
  Design   :a1, 2026-06-01, 7d
  Develop  :a2, after a1, 14d
\`\`\`

\`\`\`mermaid
pie title Languages
  "JavaScript" : 45
  "Python" : 30
  "Other" : 25
\`\`\`

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

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.

// 🎯 MINI-CHALLENGE: print a login-flow diagram source.
// Build (with console.log) the SOURCE for a flowchart that includes:
//   1. A graph direction line (graph TD)
//   2. A start box, e.g. A[Visit site]
//   3. A decision diamond, e.g. B{Logged in?}
//   4. A "Yes" arrow to a dashboard box and a "No" arrow to a login box
//
// ✅ Expected printed source (shape):
//    graph TD
//      A[Visit site] --> B{Logged in?}
//      B -->|Yes| C[Dashboard]
//      B -->|No| D[Login]
//
// Then wrap it in a mermaid fence to render it on GitHub.

// your code here

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.

Q: Is Mermaid part of the Markdown spec?

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.

Q: Can I style the colours of a diagram?

Yes. Mermaid supports themes and per-node styling with classDef and style directives, though the basics in this lesson need none of that.

Q: How do I export a diagram as an image?

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

Continue this course

• Previous: YAML Front Matter
• Next: Math with LaTeX — Write inline and block equations rendered by KaTeX or MathJax
• Quick reference: Markdown cheat sheet