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.

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{" "} is a diamond. Add text between pipes to label an arrow: A -->|Yes| B .

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.

Fill in the blanks so the program prints a flowchart with a diamond decision and two labelled arrows. Remember: {" "} 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.

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.

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.

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

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary