Skip to content

Lesson 00 – Visualizing with Mermaid

Prerequisites: This introductory lesson has no prerequisites; dive in to start diagramming right away.

Mermaid is a text-based tool for creating diagrams and flowcharts directly in Markdown. It’s ideal for visualizing ideas without leaving your code or documentation workflow. Throughout this curriculum, we use Mermaid to illustrate processes, architectures, and systems—quickly and collaboratively.

1. What is Mermaid?

  • Text-based diagrams: Write structured text and render it into flowcharts, decision trees, and more.
  • Version control friendly: Since diagrams are just text, they work well with Git diffs, pull requests, and code reviews.
  • Great for documentation: Add visual context directly inside README files, design specs, or engineering logs.

Use Mermaid to map things like:

  • Process flows and pipelines
  • System architecture or component diagrams
  • Decision trees and state machines

2. Viewing Mermaid Diagrams

You can render Mermaid diagrams in several ways:

  • On GitHub: GitHub renders Mermaid diagrams automatically in .md files—no setup required.
  • Locally in VS Code: Use the Markdown Preview Mermaid Support extension to preview diagrams as you write.
  • Online: Paste Mermaid blocks into mermaid.live to see them render instantly.
  • Exporting to PDF: When documentation is finalized, diagrams are converted alongside the Markdown.

3. Example Diagram

Here’s a basic flowchart written in Mermaid:

graph TD
    A[Start] --> B{Decision}
    B -- Yes --> C[Continue]
    B -- No  --> D[Stop]

This creates a diagram like:

Start ──> Decision ──> Continue
             │
             └────> Stop
  • Use [ ] for boxes
  • Use { } for decision branches
  • --> creates directional arrows

Try modifying the text in mermaid.live or your Markdown file to experiment with new shapes and flows.

4. Other Diagram Types

Mermaid supports more than just flowcharts. You can also create:

  • Sequence diagrams for message flows
  • Gantt charts for project timelines
  • State diagrams, class diagrams, and more

You don’t need to learn them all up front—just know they’re available when you need them.

Keep this reference nearby as you start diagramming in future lessons. The best way to learn Mermaid is to tweak a few examples and see what happens.

Next Up

Continue to Lesson 02 – Python Basics to start turning your diagrams into working code.