# Mermaid Reference

Short hints for generating Mermaid diagrams that render correctly in draw.io. draw.io's Mermaid parser covers 26 diagram types — the header keyword on the first non-directive line selects the type.

## General rules

- **Pick the type keyword carefully.** `graph`/`flowchart`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `sequenceDiagram`, `gitGraph`, `journey`, `pie`, `gantt`, `mindmap`, `timeline`, `quadrantChart`, `requirementDiagram`, `sankey-beta`, `xychart-beta`, `block-beta`, `c4Context`/`C4Container`/`C4Component`, `architecture-beta`, `radar-beta`, `packet-beta`, `venn-beta`, `treemap-beta`, `treeView-beta`, `ishikawa-beta`, `kanban`, `zenuml`. Misspelling the header yields a blank diagram.
- **No trailing punctuation on node IDs.** IDs are identifiers (`myNode`, `node_1`, `A`) — spaces, hyphens (in some contexts), and reserved words (`end`, `class`, `subgraph`) break the parse. Put display text in brackets or quotes instead: `A["User's Account"]`.
- **One statement per line.** Separate statements with newlines; `;` works as a delimiter in flowchart but not everywhere.
- **Quote labels with special characters** (`:`, `-`, parentheses, non-ASCII). Use `"` not `'`.
- **HTML in labels:** only `<br>`, `<b>`, `<i>`, `<u>` are reliable across types. Use `#` for hex colors in styles, never `rgb()`.
- **Diagrams can take a title block** for some types:
  ```
  ---
  title: My Diagram
  ---
  flowchart TD
  ```
- **Match the language of labels to the user's language** — if the user writes in German, French, etc., the diagram labels should be in that language too.

## Flowchart (most common)

```
flowchart TD
  A[Start] --> B{Decision?}
  B -->|Yes| C[Do thing]
  B -->|No| D[Skip]
  C --> E((End))
  D --> E
```

- **Direction:** `TD`/`TB` (top-down), `BT`, `LR`, `RL`.
- **Node shapes by bracket:** `[rect]`, `(rounded)`, `([stadium])`, `[[subroutine]]`, `[(cylinder)]`, `((circle))`, `{rhombus}`, `{{hexagon}}`, `[/parallelogram/]`, `[\parallelogram alt\]`, `[/trapezoid\]`, `>asymmetric]`.
- **Edges:** `-->` arrow, `---` no arrow, `-.->` dotted, `==>` thick, `<-->` bidirectional. Inline label: `A -- text --> B` or `A -->|text| B`.
- **Subgraphs:**
  ```
  subgraph Frontend
    A --> B
  end
  ```

### Styling & colors

Three ways — pick one, don't mix for the same node:

**1. Inline per-node (`style`):**
```
flowchart LR
  A[Start] --> B[End]
  style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff
  style B fill:#bbf,stroke:#f66,stroke-dasharray:5 5
```

**2. Reusable classes (`classDef` + `:::`):**
```
flowchart LR
  A:::happy --> B:::sad
  classDef happy fill:#dfd,stroke:#0a0
  classDef sad fill:#fdd,stroke:#a00
```
Or apply to many: `class A,B,C happy`.

**3. Link styling (edges):**
```
linkStyle 0 stroke:#f00,stroke-width:3px
linkStyle default stroke:#999
```
`0` = first edge in order defined; `default` targets unstyled edges.

Style properties that work: `fill`, `stroke`, `stroke-width`, `stroke-dasharray`, `color` (font color).

## Sequence diagram

```
sequenceDiagram
  participant U as User
  participant S as Server
  U->>S: Request
  S-->>U: Response
  Note right of S: Logged
```

- **Arrows:** `->` (no head), `->>` (arrow), `-->>` (dashed), `-x` (X end), `--x` (dashed X).
- **Activate/deactivate:** `activate S` / `deactivate S` or `S->>+S2: call` / `S2-->>-S: return`.
- **Blocks:** `alt/else/end`, `opt/end`, `loop/end`, `par/and/end`, `critical/option/end`.
- **Notes:** `Note left of A`, `Note over A,B: text`.
- Optional `autonumber` after header numbers the messages.

## Class diagram

```
classDiagram
  class Animal {
    +String name
    +int age
    +eat() void
  }
  class Dog
  Animal <|-- Dog : inherits
  Dog "1" --> "*" Bone : has
```

- **Relations:** `<|--` inherit, `*--` composition, `o--` aggregation, `-->` association, `..>` dependency, `..|>` realize, `<-->` bidirectional.
- **Visibility:** `+` public, `-` private, `#` protected, `~` package.
- **Annotations:** `<<interface>>`, `<<abstract>>`, `<<enumeration>>` inside the class block or via `Animal <<interface>>`.
- **Cardinality:** quoted strings flanking the arrow (`"1"`, `"0..*"`, `"*"`).

## State diagram

```
stateDiagram-v2
  [*] --> Idle
  Idle --> Running : start
  Running --> Idle : stop
  Running --> [*]
  state Running {
    [*] --> Working
    Working --> Waiting : block
    Waiting --> Working : unblock
  }
```

- Use `stateDiagram-v2`, not `stateDiagram` (v1 is legacy).
- `[*]` = start (source) or end (target) depending on direction.
- `state X { ... }` nests a compound state; `state fork1 <<fork>>`, `<<join>>`, `<<choice>>` mark junction nodes.
- Transition labels: `A --> B : event [guard] / action`.

## ER diagram

```
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER {
    string name
    string email PK
  }
```

- **Cardinality symbols:** `|o` zero-or-one, `||` exactly-one, `}o` zero-or-many, `}|` one-or-many. Mirror on both sides (e.g., `||--o{`).
- Attribute blocks list `type name [PK|FK|UK]` plus optional comment in quotes.
- Entity names are typically UPPERCASE by convention.

## Journey

```
journey
  title Morning routine
  section Wake up
    Coffee: 5: Me
    Read news: 3: Me
  section Commute
    Drive: 2: Me, Traffic
```

Each task: `Name: score(1-5): Actor[, Actor...]`. Section headers group tasks.

## Pie

```
pie showData title Browser share
  "Chrome" : 60
  "Firefox" : 20
  "Safari" : 20
```

`showData` is optional (renders the numbers). Quotes on labels, colon, numeric value.

## Gantt

```
gantt
  title Project timeline
  dateFormat YYYY-MM-DD
  section Phase 1
  Design : a1, 2025-01-01, 7d
  Build  : after a1, 14d
  section Phase 2
  Test   : 2025-01-25, 5d
```

- `dateFormat` is mandatory.
- Task line: `Name : [id,] [after id | YYYY-MM-DD], duration[d/w]`.
- Status tags: `done`, `active`, `crit` before the id (`crit a1`).

## Gitgraph

```
gitGraph
  commit
  branch develop
  checkout develop
  commit
  commit
  checkout main
  merge develop
```

Commands: `commit [id: "x"] [tag: "v1"]`, `branch name`, `checkout name`, `merge name`, `cherry-pick id: "x"`.

## Mindmap

```
mindmap
  root((Project))
    Frontend
      React
      CSS
    Backend
      Node
      DB
```

- Indentation (2-space increments) defines hierarchy.
- Root shape: `((circle))`, `[rect]`, `(rounded)`, `))cloud((`, `)hexagon(`, `{{hexagon}}`.
- No edges — they are implied by nesting.

## Timeline

```
timeline
  title Company history
  section 2020s
    2021 : Founded
    2022 : Series A
         : Launched product
  section 2030s
    2030 : IPO
```

Colon separates year/label; multiple `:` lines under one year add sub-events.

## Quadrant chart

```
quadrantChart
  title Reach vs Engagement
  x-axis Low --> High
  y-axis Low --> High
  quadrant-1 Stars
  quadrant-2 Question Marks
  quadrant-3 Dogs
  quadrant-4 Cash Cows
  Campaign A: [0.3, 0.6]
  Campaign B: [0.75, 0.85]
```

Point coords are `[0..1, 0..1]`.

## Requirement diagram

```
requirementDiagram
  requirement req1 {
    id: "1"
    text: "The system shall..."
    risk: high
    verifymethod: test
  }
  element user_story {
    type: "story"
  }
  user_story - satisfies -> req1
```

Requirement types: `requirement`, `functionalRequirement`, `performanceRequirement`, `interfaceRequirement`, `physicalRequirement`, `designConstraint`. Relations: `contains`, `copies`, `derives`, `satisfies`, `verifies`, `refines`, `traces`.

## Sankey

```
sankey-beta
Source,Intermediate,10
Source,Direct,5
Intermediate,Sink,10
```

CSV-style: `source,target,value`. No header. No `title` (use frontmatter).

## XY chart

```
xychart-beta
  title "Revenue"
  x-axis [jan, feb, mar, apr]
  y-axis "USD" 0 --> 10000
  bar [2500, 5000, 7500, 9000]
  line [3000, 4500, 6500, 8500]
```

`bar [...]` and `line [...]` can stack; order matters (later overlays earlier).

## Block

```
block-beta
  columns 3
  A B C
  D["Wide"]:2 E
  A --> D
```

`columns N` sets grid width. `Name:N` spans N columns. Edges use flowchart arrow syntax.

## C4

```
C4Context
  Person(user, "User")
  System(app, "App", "Does things")
  Rel(user, app, "Uses")
```

- Variants: `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`.
- Element helpers: `Person`, `System`, `System_Ext`, `Container`, `ComponentDb`, `Boundary(id, "label", "type")`, etc. Arguments are positional: `(id, label, [type/tech], [description])`.
- `UpdateElementStyle(tag, $bgColor="#…")` and `AddElementTag` tweak appearance.

## Architecture

```
architecture-beta
  group cloud(cloud)[Cloud]
  service api(server)[API] in cloud
  service db(database)[DB] in cloud
  api:R --> L:db
```

- Built-in icons: `cloud`, `server`, `database`, `disk`, `internet`. Suffix edge ends with `:T`, `:B`, `:L`, `:R` to pick the side.
- `group id(icon)[Label]` then `in groupId` on services places nodes.

## Radar

```
radar-beta
  title Skills
  axis js["JS"], py["Python"], go["Go"]
  curve alice["Alice"]{80, 60, 70}
  curve bob["Bob"]{50, 90, 65}
```

Axes and curves are positionally aligned — list values in axis order, 0–100.

## Packet

```
packet-beta
  0-15: "Source Port"
  16-31: "Dest Port"
  32-63: "Seq Number"
```

`start-end` (bit ranges) or single-bit `N`. Use a title frontmatter.

## Venn

```
venn-beta
  set A ["Set A"]
  set B ["Set B"]
  union A,B
  text A ["only A"]
  text A,B ["shared"]
```

Define every `union` combination whose region you plan to label. `text A,B [...]` places text in intersections.

## Treemap

```
treemap-beta
"Category"
    "Leaf 1": 40
    "Leaf 2": 60
```

Numbers are values (area-weighted). Indent (2+ spaces) for hierarchy.

## Tree view

```
treeView-beta
  "Root"
    "Child 1"
      "Grandchild"
    "Child 2"
```

Pure indentation hierarchy, no numbers.

## Ishikawa (fishbone)

```
ishikawa-beta
  Main Problem
    Category
      Cause
      Sub-cause
    Another Category
      Cause
```

First line after header is the problem; top-level indents are categories (Materials, Methods, Machinery, etc. — use whatever makes sense).

## Kanban

```
kanban
  todo[To Do]
    task1[Write spec]@{ assigned: "Alice", priority: "High" }
  doing[In progress]
    task2[Build feature]
  done[Done]
```

Columns are `id[Label]` at indent 0; cards are `id[Label]@{ metadata }` inside. Metadata keys: `assigned`, `priority` (`Very Low`/`Low`/`Medium`/`High`/`Very High`), `ticket`.

## ZenUML

```
zenuml
  @Actor User
  @Boundary Web
  @Control Service
  User -> Web: request
  Web -> Service: process()
  Service -> Web: result
```

Participant roles: `@Actor`, `@Boundary`, `@Control`, `@Entity`, `@Database`. Messages use `->` with a colon-separated label. Supports `if/else`, `while`, `par` blocks like sequence diagrams.

## When to prefer XML over Mermaid

- Precise positions / custom coordinates.
- draw.io-native shapes (AWS, Azure, GCP, P&ID, Cisco, electrical).
- Mixed shape libraries or complex multi-layer diagrams.
- Anything that needs exact colors per element with many variations — Mermaid's styling works but at scale XML is easier to reason about.

Default to Mermaid for the standard types above; reach for XML only when Mermaid's syntax clearly can't express what's needed.