Learn Mermaid with Phoebe

Stop drawing diagrams. Start typing them.

Six 45-minute sessions on mermaid, the text-to-diagram language built into GitHub, Notion, and half your toolbox. We diagram one realistic data platform end to end - flowcharts to ER models to roadmaps - and every diagram in this course is real mermaid, rendered live in your browser.

6sessions
3deep dives
20diagram types taught
45min per session

Proof, not promises: this is Nova, the running project - the diagram below is live mermaid source, rendered by mermaid.js the moment you loaded this page. Flip it to Code. Copy it. That is the whole course in one block.

flowchart LR
  ev[App events] -->|stream| ing[Ingestion]
  crm[CRM export] -.->|nightly| ing
  ing --> qa{Quality checks}
  qa -->|pass| dw[(Warehouse)]
  qa -->|fail| dlq[Quarantine]
  dw --> bi[Dashboards]
  dw --> ml[ML features]
✍️ Session 1 · easiest

Draw with text: diagrams as code

Why typed diagrams beat dragged ones, flowchart fundamentals, and your first diagram rendering in GitHub and Notion.

▶ Start hereEveryone 🗺️ Session 2 · easy

Tame the spaghetti: flowchart mastery

Subgraphs, styling classes, click links, and big-diagram hygiene - Nova's full architecture map takes shape.

Everyone 💬 Session 3 · medium

Who calls whom: sequence and state

Sequence diagrams for conversations between systems, state machines for lifecycles - the runtime side of Nova.

Builders 🗄️ Session 4 · medium

Schemas that speak: ER and class diagrams

Crow's foot cardinality you can actually read, the Nova warehouse model, and class diagrams for when structure is code.

Data teams 📅 Session 5 · hard(er)

Six diagrams for humans

Gantt, timeline, kanban, gitgraph, journey, mindmap - a breadth session for the work AROUND the system.

Leads & PMs too 🎨 Session 6 · hardest

Make it yours: the pro layer

Theming (how this course got pink), architecture and C4 diagrams, CLI exports in CI, accessibility, embedding everywhere.

Power users
easy - everyone medium - hands-on builders harder - breadth session hardest - config & tooling

Choose your path 🗺️

Everyone starts at Session 1 - the fence and the fundamentals live there. After that, follow your work.

🚀 Full journey (recommended) 1→ 2→ 3→ 4→ 5→ 6→ deep dives
📊 Data & platform people 1→ 2→ 4→ 6→ 6.1
👔 Leads, PMs & storytellers 1→ 2→ 5

The deep-dive track 🔬

Mermaid ships ~29 diagram types and half are experimental - the sessions teach the stable daily drivers deep, and these three self-paced pages cover the adventurous rest plus the power config.

6.1Data charts: pie, quadrant, xy, sankey, radar 6.2Structure extras: block, packet, treemap 6.3Power config: directives, icons, ELK, math

The knowledge map 🧠

The whole course at a glance - hover a session to spotlight its concepts, click any node to jump in.

The whole course on one sheet 📐

Seven modules: the six core sessions and three deep dives, the source-becomes-render idea the whole course rests on, which diagram answers which question, the twenty types mermaid ships, the three tools that tame a tangle, and Nova diagrammed end to end.

Download for print (2800px) Every word here is real selectable text, so it stays sharp however far you zoom.

learn mermaid
with phoebe

Stop drawing diagrams. Start typing them.
9 sessions - 20 diagram types - one running project, Nova - every diagram in the course is real mermaid

SEC-01 THE SESSIONS

CORE
six 45-minute sessions

  1. 01Draw with text: diagrams as code
  2. 02Tame the spaghetti: flowchart mastery
  3. 03Who calls whom: sequence and state
  4. 04Schemas that speak: ER and class
  5. 05Six diagrams for humans
  6. 06Make it yours: theming and shipping

DEEP DIVES
when you want the rest of it

  1. 61Numbers in pink: chart types
  2. 62Boxes with opinions: block, packet, treemap
  3. 63Under the hood: directives, icons, math
9sessions
20diagram types
1running project
45min each

SEC-02 SOURCE BECOMES RENDER

This is the whole course in one block
flowchart LR ev[App events] -->|stream| ing[Ingestion] crm[CRM export] -.->|nightly| ing ing --> qa{Quality checks} qa -->|pass| dw[(Warehouse)] qa -->|fail| dlq[Quarantine] dw --> bi[Dashboards] dw --> ml[ML features]
That text is Nova's ingestion path. Paste it into GitHub or Notion and it renders. Nothing to drag, nothing to re-export when the pipeline changes.
Why typed beats dragged

A diagram you typed lives in the repo next to the thing it describes. It diffs, it reviews, and it can be wrong in a pull request rather than wrong on a wall.

SEC-03 WHICH DIAGRAM, WHICH QUESTION

01
flowchartHow does work move through the system?
03
sequenceDiagramWho calls whom, and in what order?
03
stateDiagram-v2What state is this thing in, and what moves it?
04
erDiagramHow do the tables relate, and on which keys?
04
classDiagramWhat shape does the object have?
05
ganttWhen does the work land, and what blocks it?
Pick the diagram from the question you are answering, not from the one you can already draw.

SEC-04 THE LADDER

1
nodes, arrows, labels your first diagram rendering in GitHub and Notion
01
2
subgraphs, classes structure and meaning, so big diagrams stay readable
02
3
sequence, state runtime stories: who calls whom, and what state it is in
03
4
erDiagram, classDiagram the data model, in text
04
5
gantt, timeline, journey six diagrams about the work around the system
05
6
theme, config, ship make it yours, then put it where people read it
06
7
pie, xychart, sankey, radar when the answer is a number, not a shape
61
8
block, packet, treemap, kanban layouts with opinions of their own
62
9
directives, icons, math under the hood, once the defaults stop fitting
63
How to climb it

Sessions 1 to 4 diagram the system. Session 5 diagrams the work around it. Session 6 is the one that gets your diagrams accepted, because a diagram nobody can theme is a diagram nobody ships.

SEC-05 ONE PLATFORM, EVERY VIEW

Nova is the running project. The same platform is diagrammed nine ways, so each type is learned against something you already understand.
1
THE FLOWevents and CRM in, warehouse and quarantine out
2
THE CALLSwhich service asks which, and when it waits
3
THE STATESwhat a record can be, and what moves it
4
THE SCHEMAthe tables and the keys that join them
5
THE PLANthe roadmap, the releases, the backlog
6
THE POLISHtheme it, configure it, ship it into the docs

SEC-06 THE THREE TOOLS THAT TAME A TANGLE

Subgraphs, for structureA flat list of thirty nodes is a tangle. Grouped into four named regions it is a diagram. Ask: what are the three or four areas this really has?
Classes, for meaningColour that repeats is a legend. Colour that does not repeat is decoration. Ask: does every fill mean exactly one thing?
Hygiene, for the next readerConsistent direction, short labels, no crossing where a reorder would do. Ask: can someone follow this without me narrating?
The spaghetti testIf you cannot trace one path from entry to exit without losing your place, the diagram is not finished. Ask: where does a new event enter, and where does it end?
Session 2 is the one people thank you for

Session 1 gives you nodes and arrows, which is enough to make a mess quickly. Session 2 is the difference between a diagram you drew and a diagram someone else can read.

SEC-07 THE TWENTY TYPES

systems6

  • flowchart
  • sequenceDiagram
  • stateDiagram-v2
  • erDiagram
  • classDiagram
  • requirementDiagram

people + time6

  • gantt
  • timeline
  • journey
  • kanban
  • gitGraph
  • mindmap

numbers + shape8

  • pie
  • xychart-beta
  • sankey-beta
  • radar
  • quadrantChart
  • block-beta
  • packet-beta
  • treemap
Every one of these renders in the browser during the course, from source you can copy.
learn mermaid with phoebe 9 sessions - 20 diagram types - 1 platform diagrammed end to end by Phoebe Fu