Mermaid

Mermaid Diagram Generator

Quick Start: Wrap diagram source in a ```mermaid fenced code block. No HTML, no external scripts — the renderer handles it.

flowchart LR
  A[Browser] --> B[CDN]
  B --> C[API]
  C --> D[(Postgres)]

Why Mermaid

This is the diagram format with the widest renderer support today. Default to Mermaid unless you specifically need draw.io's shape libraries, PlantUML's stdlibs, or Vega's data binding.

When to use this skill vs. others

Critical Rules

Rule 1: Fenced block only

Always use ```mermaid exactly — not ```Mermaid, not ```mmd. Renderers are case-sensitive.

Rule 2: First line declares diagram type

The first non-empty line must be the type keyword. Mermaid won't auto-detect.

flowchart LR        ← required
sequenceDiagram     ← required
classDiagram        ← required
erDiagram           ← required
stateDiagram-v2     ← required (note: -v2 is the modern syntax)
gantt               ← required
mindmap             ← required
C4Context           ← required

Rule 3: Direction matters for flowcharts

flowchart LR (left-right), TB / TD (top-bottom), RL, BT. Pick based on reading flow — pipelines = LR, hierarchies = TB.

Rule 4: IDs vs. labels

Node id is what edges reference; the bracketed text is the label.

flowchart LR
  api[API Gateway]
  db[(Postgres)]
  api --> db

api and db are IDs (no spaces). Labels can have spaces and Markdown.

Rule 5: Shape syntax encodes meaning

Rule 6: Edge styles signal flow type

Rule 7: Use subgraphs for grouping

flowchart LR
  subgraph aws[AWS us-east-1]
    api --> db
  end
  user --> aws

Diagram type cheatsheet

Examples

Static export

For PDF / slide / static-site embedding when the renderer doesn't speak Mermaid:

npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -w 1600

-t dark for dark theme, -c config.json for custom theming.

Best Practices

1. Keep node IDs short. api, db, lb — not apiGatewayService. Labels carry the description.
2. Direction matches reading flow. Pipelines and request flows: LR. Trees and inheritance: TB.
3. Use %%{init: {...}}%% at the top to override theme/font globally for that diagram only:

   %%{init: {'theme':'neutral', 'flowchart': {'curve':'basis'}}}%%
   flowchart LR
   

4. Don't fight the layout engine. Mermaid auto-routes — if it looks wrong, the structure is wrong, not the layout. Restructure with subgraphs before adding linkStyle.
5. One concept per diagram. Don't try to show users + infra + data flow + auth in one flowchart. Split.
6. Comment with %% — useful for marking sections in long sequence diagrams.
7. GitHub renders Mermaid 4.x. New diagram types like architecture-beta may not work everywhere — check renderer support before relying on them in shared docs.