Diagrams as Code with Mermaid

State Diagrams and Gantt Charts

These two diagram types answer the same class of question: what happens over time? State diagrams track an entity moving through statuses — a request, an order, a user session. Gantt charts track work moving through a schedule. Same underlying question, completely different shapes of syntax.

stateDiagram-v2: the fundamentals

Always use stateDiagram-v2 — the older stateDiagram keyword still parses but uses a different renderer with limited layout control.

The most important symbol is [*], which marks entry and exit:

stateDiagram-v2
    [*] --> Draft
    Draft --> PendingReview : submit
    PendingReview --> Published : approve
    PendingReview --> Draft : reject
    Published --> Archived : archive
    Archived --> [*]

A colon after a transition adds a label. [*] as the source means the lifecycle starts here; as the target, this is terminal. A diagram without a [*] entry technically renders, but the reader has no idea where the lifecycle begins — always include it.

State IDs can't contain spaces. If you need a multi-word display name, alias it:

state "Pending Review" as PendingReview

After that declaration, PendingReview is what you write in transition lines; "Pending Review" is what renders in the box.

Want a horizontal layout? Add direction LR on the line right after stateDiagram-v2 — this is a v2-only feature and one more reason to always use the modern keyword.

Composite states

When a state has its own internal lifecycle, nest it with curly braces:

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : request in
        Processing --> Idle : response sent
        Processing --> Failed : timeout
        Failed --> Idle : retry
    }

    Active --> Terminated : shutdown
    Terminated --> [*]

The outer world sees Active as a single state — you enter and exit it as a unit. Internally it has its own [*] entry that fires when Active is entered. The outer Active --> Terminated transition fires regardless of which inner sub-state was active at the time. Nesting deeper than two levels usually signals the diagram should be split — same rule as with subgraphs in flowcharts.

Concurrency: parallel regions and fork/join

Two ways to model activity that happens simultaneously:

Concurrent regions inside a composite state, separated by --:

stateDiagram-v2
    state "Order Processing" as Proc {
        [*] --> PaymentPending
        PaymentPending --> PaymentConfirmed : paid
        PaymentConfirmed --> [*]
        --
        [*] --> InventoryCheck
        InventoryCheck --> Reserved : ok
        Reserved --> [*]
    }

The -- line splits the composite state box into horizontal swim lanes that run independently.

Fork/join for branches that diverge and later reconverge:

stateDiagram-v2
    [*] --> fork_state
    state fork_state <<fork>>
    fork_state --> RunTests
    fork_state --> BuildDocs

    RunTests --> join_state
    BuildDocs --> join_state
    state join_state <<join>>
    join_state --> Deploy
    Deploy --> [*]

<<fork>> and <<join>> are state stereotypes — the rendered result is a solid horizontal bar, the standard UML convention. Use <<fork>> when multiple things must happen simultaneously; <<join>> when all must complete before the flow continues.

---

Gantt charts: the date/axis setup

Switch keyword to gantt. The lines to write every time:

gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    title       Website Launch Plan

dateFormat tells the parser how to read the dates you write in task lines. Skip it and any task with an absolute start date won't parse — you get a blank diagram with no error message whatsoever. YYYY-MM-DD is the safest choice and almost universal.

axisFormat controls how dates appear on the rendered timeline, using strftime notation: %b %d gives "Jan 06", %m/%d gives "01/06", %d gives just the day number. This affects display only, not parsing.

Task syntax and flags

Tasks live under section headers. The format:

Task label  :flags, id, start, duration

A realistic project plan:

gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %b %d
    title       API v2 Launch

    section Design
    Define endpoints      :done,  des1, 2024-03-01, 5d
    Review with team      :done,  des2, after des1, 2d

    section Development
    Implement auth        :active, dev1, after des2, 7d
    Write integration tests : dev2, after dev1, 4d

    section Launch
    Deploy to staging     :crit, dep1, after dev2, 1d
    Go live               :milestone, live, after dep1, 0d

Flag reference:

Flags combine freely: :crit, done marks a finished critical-path task. The parser recognizes those four keywords as flags; anything else in that position is treated as a task ID. So :dev2, after dev1, 4d assigns the id dev2 with no status flag.

Dependencies and milestones

after taskId as the start value makes a task begin the moment the referenced task ends. Chain multiple predecessors — after dev1 dev2 — and the task waits for both to finish before starting. This is the Gantt counterpart to <<join>> in state diagrams.

Milestones mark a point in time rather than a span of work. The 0d duration is what triggers the diamond rendering:

Go live  :milestone, live, after dep1, 0d

excludes weekends at the top level removes those days from duration calculations — a 5-day task starting Thursday automatically extends into the following week.

Quick check

1. Draw a stateDiagram-v2 for a support ticket: Open → InProgress → PendingCustomer → Resolved → Closed → [*], with an edge from Closed back to Open labeled "re-open."

2. Add a composite state inside InProgress with two sub-states: Assigned and WorkingOnFix.

3. Write a five-task Gantt for a small feature rollout — at least one done task, one active, one crit, and a milestone at the end. Use after dependencies throughout.

The next submodule covers layout control, styling with classDef, theme variables, and clickable nodes — where your own-site rendering setup really starts to pay off.