Mermaid Flowchart Tutorial: Embed Diagrams in GitHub, Notion, and Docs

Mermaid lets you describe diagrams in plain text inside Markdown. When GitHub, GitLab, Notion, or Obsidian render the page, the text becomes a flowchart. That means diagrams live next to your code, review cleanly in pull requests, and update without re-exporting PNG files.

This tutorial covers core flowchart syntax, real examples, embedding tips, and how FreeFlowCharts can export Mermaid when you prefer a visual editor first.

Why Mermaid for engineering docs

Minimal flowchart

In a Markdown file (GitHub README example):

flowchart TD

A[Start] --> B{Valid input?}

B -->|Yes| C[Create account]

B -->|No| D[Show errors]

C --> E[Send verify email]

D --> B

E --> F[End]

Notes:

Node shapes you will use most

Subgraphs for swimlanes-ish grouping

flowchart LR
  subgraph Client
    A[Submit form]
  end
  subgraph API
    B{Auth OK?}
    C[Write DB]
  end
  A --> B
  B -->|Yes| C
  B -->|No| D[401 response]

Subgraphs are not full swimlanes, but they clarify system boundaries in architecture docs.

CI/CD example

flowchart TD
  push[Git push] --> build[Build]
  build --> test[Unit tests]
  test --> ok{Tests pass?}
  ok -->|No| fail[Fail pipeline]
  ok -->|Yes| review[Code review]
  review --> merge{Approved?}
  merge -->|No| fix[Request changes]
  fix --> push
  merge -->|Yes| deploy[Deploy staging]
  deploy --> smoke[Smoke tests]
  smoke --> prod{Promote?}
  prod -->|Yes| live[Production]
  prod -->|No| hold[Hold release]

Support escalation example

flowchart TD
  t[Ticket created] --> l1[L1 triage]
  l1 --> known{Known issue?}
  known -->|Yes| kb[Send KB article]
  known -->|No| sev{Severity}
  sev -->|P1| l2[Page L2]
  sev -->|P2/P3| queue[L1 queue]
  queue --> resolve{Resolved?}
  l2 --> resolve
  resolve -->|No| l3[Escalate L3]
  resolve -->|Yes| close[Close ticket]
  kb --> close
  l3 --> close

Embedding in GitHub

Tip: Keep diagrams under ~30 nodes in README files. Link to a longer FreeFlowCharts share URL for full interactive views.

Embedding in Notion

Notion supports Mermaid in code blocks on many plans/workspaces (availability can vary). Create a code block, set language to Mermaid, paste the source, and toggle preview if available. For guaranteed visual fidelity, export PNG from FreeFlowCharts and attach the image, while keeping Mermaid in Git as the source of truth.

Obsidian and other Markdown tools

Obsidian’s Mermaid support is excellent for personal knowledge bases. Paste the same fenced blocks. For static site generators, use a Mermaid plugin or pre-render SVG in CI.

Visual editor → Mermaid with FreeFlowCharts

If you think better on a canvas:

This hybrid workflow is popular with PMs who draft visually and engineers who want text in Git.

Common Mermaid pitfalls

When not to use Mermaid

Next steps