Draw with text: diagrams as code

Mermaid is an open-source JavaScript library (70k+ GitHub stars, built into half the tools you already use) that renders diagrams from a markdown-ish text syntax. You describe WHAT connects to what; mermaid decides where boxes go and draws the SVG.

Why this matters to you

• Diagrams stop rotting. A PowerPoint architecture slide is stale the week after it's made. A mermaid block sits next to the code or doc it describes and gets updated in the same pull request.
• Diagrams become reviewable. "You removed the validation step" is visible in a text diff. Nobody can diff a PNG.
• Speed. Typing 6 lines beats aligning 6 boxes. Layout is the machine's job now.
• AI speaks it fluently. Ask Claude or ChatGPT to "diagram this as mermaid" and you get working source you can paste anywhere - text diagrams are the native diagram format of the AI era.

Every mermaid diagram has the same skeleton: a diagram type keyword on the first line, then statements describing content. That first word decides the entire grammar that follows.

flowchart LR
  %% this is a comment - renderers ignore it
  idea[An idea] --> diagram[A shared picture]

• Line 1: the type. flowchart, sequenceDiagram, erDiagram, gantt, mindmap... ~15 stable types, each with its own mini-language. This course teaches the daily-driver set.
• Direction (flowcharts): LR = left to right, TD = top down. One flag, whole layout flips.
• Comments: lines starting %% are ignored - leave notes for the next editor.
• Indentation is cosmetic - mermaid doesn't care, but your reviewers do. Indent statements two spaces.

Under the hood, mermaid parses your text into a graph structure, hands it to a layout engine (dagre by default; ELK optionally for complex graphs - Session 6) that computes where every node and edge should sit, then emits SVG styled by the active theme. Three consequences worth knowing:

• You trade pixel control for speed. You cannot nudge one box 3px left, and that is the deal: mermaid is for thinking and communicating, not print-perfect posters. When exact layout truly matters, export the SVG and refine elsewhere.
• Layout can change between versions - same source, slightly different arrangement. The MEANING never changes; the placement might. This is why source, not screenshots, is what you commit.
• Themes restyle everything. The pink diagrams on this page are stock mermaid with a custom theme (Session 6 shows you exactly how). One config block, whole-deck restyle.

Fluency includes knowing the tool's edges. Reach for something else when:

• Pixel-perfect brand visuals - a marketing one-pager wants Figma or Illustrator, not auto-layout.
• Huge graphs - 200+ nodes turns into spaghetti in any auto-layout tool. Split into linked smaller diagrams instead (we do this with Nova in Session 2).
• Free-form spatial sketching - if the POSITION of things is the meaning (a floor plan, a customer journey map on a wall), a canvas tool like Excalidraw or tldraw fits better.

A node is an ID plus an optional label: ing[Ingestion job]. The brackets around the label pick the shape, and shapes carry meaning - readers decode them before reading a single word.

flowchart LR
  a[Process step] --> b(Soft process)
  b --> c{Decision?}
  c -->|yes| d[(Database)]
  c -->|no| e([Start / end])

Node IDs (a, ing, dw) are how you reference nodes later - keep them short and meaningful. The label is what humans read. Mention a node ID again anywhere and mermaid knows it's the same node - no duplicates drawn.

Edges are the arrows. Three styles cover nearly everything: solid --> for normal flow, dotted -.-> for optional/async, thick ==> for the critical path. Add a label with pipes: a -->|nightly| b.

flowchart LR
  src[App events] -->|stream| ing[Ingestion]
  crm[CRM export] -.->|nightly batch| ing
  ing ==> dw[(Warehouse)]
  dw --> dash[Dashboards]
  dw -.-> ml[ML features]

• Chain in one line: a --> b --> c works, and a & b --> c fans two nodes into one.
• No arrowhead: a --- b for plain association lines.
• Longer arrows nudge layout: extra dashes (---->) ask for extra rank distance - a gentle layout hint, not a command.

The token after flowchart sets flow direction: TD (top-down), LR (left-right), BT, RL. Rule of thumb: processes read LR like a sentence; hierarchies and decision trees read TD. When a diagram feels cramped, flipping direction is the first thing to try - it's free.

Mermaid errors look scarier than they are: "Parse error on line 3... Expecting 'SEMI', 'NEWLINE'..." decodes as "line 3 confused me". The usual suspects, in order:

• Unquoted special characters in a label - parentheses, brackets, colons. Fix: quote the label.
• A typo in the arrow - -> instead of --> (flowchart arrows need two dashes).
• Wrong grammar for the diagram type - flowchart syntax in a sequenceDiagram block, or vice versa. Check line 1 first.
• A reserved word as a node ID - naming a node end breaks flowcharts; use End or fin.

Debugging habit: comment out half the lines with %%, re-render, and bisect until the guilty line is obvious. In mermaid.live the error appears as you type, so you always know WHICH edit broke it.

In GitHub (README, issues, PRs, wikis), GitLab, Obsidian, and most docs platforms, you get a rendered diagram by fencing mermaid source as a code block with the mermaid language tag:

• GitHub: works in README files, issues, pull requests, discussions, and wikis. Diagram renders on page view.
• Notion: type /code, pick Mermaid as the language - Notion shows code and preview side by side or preview only.
• Obsidian: same fence, renders in preview mode. Your second brain gets diagrams for free.
• VS Code: install a mermaid preview extension and the fence renders in markdown preview - diagrams in your repo docs, visible while you edit.

mermaid.live is the official editor: source on the left, live render on the right, errors as you type. It's where you DRAFT; the fence is where diagrams LIVE. The share button encodes your whole diagram into the URL - no account, no save button, the link is the file. Every diagram block on this page has an "Edit on mermaid.live" button for exactly this reason.

• Docs generators - MkDocs (Material), Docusaurus, VitePress, Hugo all render mermaid fences with a one-line config. Your architecture docs stay text end to end.
• This page loads mermaid.js from a CDN and renders every block client-side - about 10 lines of JavaScript, shown in full in Session 6.
• AI assistants - Claude and ChatGPT both emit mermaid on request ("diagram this pipeline as a mermaid flowchart"). You review the text, fix labels, paste into the fence. Minutes from description to committed diagram.
• Exports - mermaid.live exports PNG/SVG for slides; the mermaid CLI (mmdc) batch-exports in CI (Session 6).