Mermaid Flowcharts (with UML Meanings)

From Qiki
Jump to navigation Jump to search

Mermaid Flowcharts (with UML Meanings)

Beginner‑friendly guide with short explanations and many examples.


1) What is Mermaid Flowchart?

A flowchart is a diagram made of nodes (shapes with text) connected by edges (lines/arrows). Mermaid lets you write text that renders into a diagram. Mermaid Flowchart ≠ UML: Mermaid is a diagram tool; UML is a modeling standard. In this guide we show the closest UML ideas for each Mermaid feature. (Mermaid)


2) Quick start (minimal example)

flowchart TD
  Start([Start]) --> Check{In stock?}
  Check -->|Yes| Ship[Ship order]
  Check -->|No| Backorder[Backorder]

What it shows: A top‑down flow with one decision and two outcomes.


3) Directions and graph keyword

Use flowchart (or its alias graph) plus a direction:

  • TB / TD = top‑down
  • BT = bottom‑up
  • LR = left‑to‑right
  • RL = right‑to‑left

Direction changes layout only (no UML meaning). (Mermaid)

TD example 

flowchart TD
  A[Start] --> B[Step] --> C[End]

What it shows: A vertical (top‑down) layout.

LR example 

flowchart LR
  A[Start] --> B[Step] --> C[End]

What it shows: A horizontal (left‑to‑right) layout.


4) Nodes: ids, labels, text

  • Id vs label: A[Text] creates node id A with label Text. You can set label once and reuse id later.
  • Unicode/markdown in labels: put the label in double quotes, and markdown (bold/italic) works in labels.
  • Escape special characters either by quoting ("...") or using HTML entities like ", <, #. (Mermaid)
flowchart LR
  A["Hello **world** and *friends*"] --> B["Unicode: “Привет”"]
  C["Quote: "Hi", less-than: <, hash: #"]

What it shows: Ids, markdown in labels, and escaped characters.

Gotchas

  • Using the lowercase word end as a node label breaks parsing. Use End or END instead. (Mermaid)
  • If a node id starts with o or x right after a link operator (e.g., A---oB), Mermaid may think you want a circle or cross edge. Add a space (A--- oB) or capitalize (A---OB). (Mermaid)


5) Shapes (classic bracket syntax)

Mermaid Syntax Visual Shape (name) Typical Flowchart Role Closest UML Meaning Example
A[Text] Rectangle Process/step Action (UML Activity uses rounded rectangles; this is a near match) A[Process step]
A(Text) Rounded rectangle Process/step Action (best visual match) A(Start job)
A([Text]) Stadium / terminator Start/End in flowcharts No direct UML; UML start/end use circles A([Begin])
A[[Text]] Subroutine / double-rect Subprocess Call Behavior Action (sub‑activity) A[[Recalculate total]]
A[(Text)] Cylinder (database) Data store DataStoreNode / Object Node A[(Orders DB)]
A((Text)) Circle Connector/terminator in flowcharts Initial node (if filled) or junction; style may be needed A((Start))
A(((Text))) Double circle End/terminator Activity final node A(((End)))
A{Text} Diamond (rhombus) Decision Decision / Merge node A{In stock?}
A{{Text}} Hexagon Preparation / condition No standard UML; use an Action with note/stereotype A{{Prepare}}
A>Text] Asymmetric Off‑page link / special step No standard UML A>Go to page 2]
A[/Text/] Parallelogram Input/Output Often modeled as Object node or specific Action (e.g., accept input) A[/User input/]
A[\Text\] Parallelogram alt Input/Output Same as above A[\Show result\]
A[/Text\] Trapezoid Manual operation (base bottom/top varies) No standard UML; use Action with «manual» stereotype A[/Manual step\]
A[\Text/] Trapezoid alt Manual operation (alt) Same as above A[\Manual step/]

Note: the asymmetric shape currently has only one orientation (no mirrored form). (Mermaid) 

flowchart LR
  R[Rect] --> RR(Rounded)
  ST([Terminator]) --> D{Decision}
  DB[(DB)] --> C((Circle)) --> CC(((End)))
  HEX{{Prepare}} --> S>Asymmetric]
  IN[/Input/] --> OUT[\Output\]
  M[/Manual\] --> M2[\Manual/]
  SUB[[Subroutine]] --> R

What it shows: A sampler of classic shapes connected in one flow. (Mermaid)

Reminder: These are flowchart symbols. UML Activity Diagrams mainly use Actions (rounded rectangles), Decisions (diamonds), Initial (filled circle), Final (bullseye), and Fork/Join bars. When a flowchart shape has no exact UML meaning, use an Action plus a note/stereotype, or an Object Node.


6) Expanded shapes (v11.3+)

Mermaid v11.3+ adds a general way to assign shapes:

  • Generic assignment: A@{ shape: rect }
  • Many new shapes are available, e.g.:
    • circle (Start) → UML Initial node
    • dbl-circ (Stop) → UML Activity final
    • hex (Prepare) → No standard UML; use Action + stereotype
    • fork (Fork/Join bar) → UML Fork/Join
    • cyl (Database) → UML DataStoreNode/Object Node
    • doc (Document) → Usually Object Node or Action
    • text (Text block) → No UML semantics (note-like) (Full list in docs; feature tag v11.3.0+.) (Mermaid)
flowchart LR
  S@{ shape: circle, label: "Start" } --> P@{ shape: rect, label: "Process" }
  P --> F@{ shape: fork, label: "Fork/Join" } --> E@{ shape: dbl-circ, label: "Stop" }

What it shows: New shape syntax mixed with classic flow.


7) Edges (links) and labels

Edge Syntax Meaning Closest UML Meaning Example
A --> B Directed edge with arrow Control flow A --> B
A --- B Open line (no arrow) No standard in UML Activity A --- B
A -.-> B Dotted arrow Not standard in UML Activity (dashed lines mean dependency elsewhere) A -.-> B
A ==> B Thick arrow Style only, no UML semantics A ==> B
text | B Labeled edge UML guards like [x > 0] Yes | Ship
A o--o B, B <--> C, C x--x D Circle/cross heads, both‑ways No standard UML meaning A o--o B
A Ryan (talk) B Invisible link (layout only) No UML meaning A Ryan (talk) B
a --> b & c --> d Chaining / parallel link syntax Convenience only a --> b & c --> d
Extra dashes (---->, ===>, -..->) Longer rank spacing Layout only B ----> E

Mermaid supports all of the above, plus link lengthening using extra dashes/equal/dot characters and multi‑directional arrows. (Mermaid) 

flowchart LR
  Start([Start]) --> Q{Approved?}
  Q -->|Yes| Go[Proceed]
  Q ---->|No| Fix[Fix and retry]

What it shows: Yes/No labels and “extra dashes” to push the No edge further. (Mermaid)


8) Subgraphs (groups)

You can group nodes with subgraph ... end. You can connect edges to and from subgraphs. You can also set a direction inside a subgraph. Limitation: if any node in a subgraph links outside, the subgraph’s direction is ignored and it inherits the parent direction. (Mermaid) 

flowchart LR
  subgraph Fulfillment
    direction TB
    Pick[Pick items] --> Pack[Pack box]
  end

  Order([Order]) --> Fulfillment
  Pack --> Ship[Ship]

  %% Because Pack links to Ship (outside), the TB direction inside
  %% may be ignored and Fulfillment will inherit LR from the parent.

What it shows: A subgraph with internal direction and edges to/from outside; demonstrates the direction limitation.


9) Styling and classes

  • Single node: style nodeId fill:#fee,stroke:#c33,stroke-width:2px,color:#900
  • Classes: classDef warn fill:#fff3cd,stroke:#856404; then class X warn; (or attach with :::).
  • Links: linkStyle N ... (use link number(s) or default) to style links.
  • Curves: set curve types like cardinal, stepBefore, etc., for all edges via config; per‑edge curve is possible when the edge has an ID (v11.10+). (Mermaid)
%% Diagram-level curve style via directive
---
config:
  flowchart:
    curve: stepBefore
---
flowchart LR
  A[Start] --> B[Warned edge] --> C[End]
  style C fill:#e6ffed,stroke:#1f883d
  classDef warn fill:#fff3cd,stroke:#856404
  class B warn
  linkStyle 1 stroke:#555,stroke-width:3px

What it shows: A custom node color, a class, a styled link, and a diagram‑level curve. (Edge‑level curves require Edge IDs, v11.10+.) (Mermaid)


10) Interaction (click)

You can make nodes clickable—either call a JS callback or go to a URL. This works when Mermaid’s securityLevel is loose (not strict). (Mermaid) 

flowchart LR
  Home[Home] --> Repo[Repo]
  click Home "https://example.com" "Go home"
  click Repo href "https://github.com" "_blank"
  %% For callbacks (requires securityLevel: 'loose'):
  %% click Home callback "Tooltip text"

What it shows: Clickable nodes (URL and callback).


11) Icons & images (v11.3+/v11.7+)

  • Special shapes (v11.3+): icon and image are built‑in node shapes.
  • Font Awesome support: You can use FA icons; registering icon packs is v11.7+, or include FA CSS. (Mermaid)
flowchart TD
  I@{ shape: icon, icon: "fa:fa-user", form: "circle", label: "User", pos: "b", h: 48 }
  L@{ shape: image, img: "https://example.com/logo.png", label: "Logo", pos: "t", h: 48, constraint: "on" }
  I --> L

What it shows: An icon node and an image node connected. (Icons need FA CSS or a registered pack; see docs.) (Mermaid)


12) Common pitfalls (quick list)

  • Lowercase end as a node breaks flowcharts; write End or END. (Mermaid)
  • Leading o / x after a link operator can be parsed as circle/cross edge heads—add a space or capitalize. (Mermaid)
  • Special characters: quote or escape with entities (e.g., &quot;, &lt;, &#35;). (Mermaid)
  • Subgraph direction limitation: links to outside make the subgraph inherit the parent’s direction. (Mermaid)
flowchart LR
  %% Bad (would become a circle head):  Dev --- oPs
  %% Good (space or capital):
  Dev --- Ops

What it shows: The spacing/capitalization workaround for o/x.


13) UML mapping cheat sheet (compact)

Mermaid (Flowchart) UML Activity meaning
Rounded rectangle Action
Diamond Decision / Merge
Filled circle Initial node
Double circle (bullseye) Activity final node
Thick bar (fork shape) Fork/Join (bar)
Cylinder DataStoreNode / Object Node
Parallelogram (I/O) Usually Action with «input»/«output», or Object Node
Stadium / Asymmetric / Trapezoid No standard UML; use Action + note/stereotype 
flowchart LR
  I@{ shape: circle, label: "Initial" } --> A(Rounded Action)
  A --> D{Decision} --> F@{ shape: dbl-circ, label: "Final" }
  A --> B@{ shape: fork, label: "Fork/Join" }

What it shows: Typical UML‑like elements using Mermaid shapes.


14) Two worked examples

1) Order flow

flowchart LR
  subgraph Fulfillment
    direction TB
    Check{In stock?}
    Ship[Ship order]
    Wait[Wait for stock]
  end

  Start([Start]) --> Check
  Check -->|Yes| Ship --> Done(((Done)))
  Check -->|No| Wait --> Check

What it shows: A decision with Yes/No labels, a loop back, and a subgraph grouping fulfillment tasks. (Subgraph may inherit parent direction if nodes link outside.) (Mermaid)

2) Login flow

flowchart TD
  Ask[/Enter username & password/] --> Verify[(Users DB)]
  Verify --> Valid{Valid?}
  Valid -->|Yes| Go[Open dashboard]
  Valid -->|No| Show[\Show error/]
  Go --> End(((End)))

What it shows: I/O nodes, a database (cylinder), a decision, and an end node.


15) Final checklist

  • ☒ Syntax validated: no lowercase end nodes; no accidental o/x edge heads. (Mermaid)
  • ☒ Every section has at least one code example and a What it shows line.
  • ☒ UML meanings are clearly stated or marked “no standard UML equivalent.”
  • ☒ Direction is layout only; flowchart and graph are aliases. (Mermaid)
  • ☒ Edge features shown: labels, multi‑directional arrows, dotted/thick, invisible, chain &, and extra dashes for spacing. (Mermaid)
  • ☒ Styling: node style, classDef/class, linkStyle, and curve styles; note edge‑level curves with Edge IDs (v11.10+). (Mermaid)
  • ☒ Advanced shapes: expanded shapes (v11.3+) and Font Awesome icon packs (v11.7+) included. (Mermaid)


Source of truth: Mermaid Flowchart documentation (v11.12.0 page at time of writing). See sections on directions, shapes (classic and expanded), edges, subgraphs (including the direction limitation), styling/classes (including curves and edge IDs), click interaction, and icons/images. (Mermaid)

Retrieved from "https://www.qfqu.com/w/index.php?title=Mermaid_Flowcharts_(with_UML_Meanings)&oldid=93"