Mermaid

Mermaid draws diagrams from plain text: flowcharts, sequence, class, state, ER, Gantt and Git graphs. Write it in a fenced mermaid block so it renders on GitHub and in many editors, or render files with mmdc (mermaid-cli).

Documentation: Mermaid documentation · Mermaid CLI · GitHub: creating diagrams Project: Mermaid

Verification: syntax checked against the Mermaid documentation and the mermaid-cli source. The diagrams were not rendered locally (mermaid-cli needs a bundled Chromium), so a version difference or typo is possible. Test in the Mermaid Live Editor.

Basics #

```mermaid
flowchart LR
    A[Client] --> B[Proxy] --> C[App]
```

Flowchart #

graph is an older alias of flowchart. Direction is TB (or TD), BT, LR or RL.

flowchart TD
    A[Request] --> B{Cached?}
    B -->|Yes| C[Serve from cache]
    B -->|No| D[(Database)]
    D --> C
    subgraph Edge
        B
    end

Sequence Diagram #

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server
    C->>+S: GET /health
    alt healthy
        S-->>-C: 200 OK
    else failing
        S-->>C: 503
    end
    Note over C,S: Retry after 5 seconds

Class Diagram #

classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog
    Animal <|-- Dog
    Dog "1" --> "*" Toy : owns

State Diagram #

Use stateDiagram-v2.

stateDiagram-v2
    [*] --> Idle
    Idle --> Running : start
    Running --> Idle : stop
    Running --> Failed : error
    Failed --> [*]

ER Diagram #

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        int id PK
        string name
    }
    ORDER {
        int id PK
        int customer_id FK
    }

Gantt #

gantt
    title Migration
    dateFormat YYYY-MM-DD
    section Build
    Design  :done, des1, 2025-01-01, 5d
    Develop :active, dev1, after des1, 10d
    Launch  :milestone, m1, after dev1, 0d

Git Graph #

gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop tag: "v1.0"
    commit

Themes and Configuration #

Theme names (Mermaid documentation): default, neutral, dark, forest, base, plus newer looks such as neo, neo-dark, redux, redux-dark, redux-color and redux-dark-color on recent versions. Only base accepts custom themeVariables.

Frontmatter at the top of the diagram is the current method:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#BB2528"
    lineColor: "#F8B229"
---
flowchart LR
    A --> B

The older init directive still works and goes on the line before the diagram:

%%{init: {"theme": "forest", "flowchart": {"curve": "linear"}}}%%

GitHub and Editors #

mermaid-cli (mmdc) #

Install with npm install -g @mermaid-js/mermaid-cli, or run it with npx -p @mermaid-js/mermaid-cli mmdc. It drives a headless Chromium through Puppeteer.

Run in Docker without installing Node: docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/data" minlag/mermaid-cli -i diagram.mmd -o diagram.svg. In a container as root, Chromium may need {"args": ["--no-sandbox"]} in the Puppeteer config (unverified here).

Troubleshooting #

See Also #

• Markdown
• Obsidian
• Joplin
• VSCode (Visual Studio Code)
• Git