Mermaid Reference Manual (Hybrid Edition)

A practical, readable guide to Mermaid 10.9.5

1. WHAT MERMAID IS

Mermaid is a “diagrams as code” tool. You write plain text, and Mermaid renders diagrams such as:

• Flowcharts
• Sequence diagrams
• Class diagrams
• State machines
• ER diagrams
• Journey diagrams
• Gantt charts
• Pie charts
• Timelines
• Mindmaps

Why it’s useful:

• Works in HTML, Markdown, and static sites
• Version-controlled diagrams live alongside code
• Searchable and diffable
• Consistent, themeable visuals across a project or book

This manual is hybrid: part explanation, part ready-to-paste reference.

2. SETUP AND INITIALIZATION

2.1. Include the CDN Script

<script src="https://unpkg.com/mermaid@10.9.5/dist/mermaid.min.js"></script>

2.2. Global Initialization

<script>
document.addEventListener("DOMContentLoaded", () => {
    mermaid.initialize({
        startOnLoad: true,
        theme: "dark",
        themeVariables: {
            primaryColor: "#020617",
            primaryTextColor: "#e5e7eb",
            primaryBorderColor: "#4b5563",
            lineColor: "#9ca3af",
            noteBkgColor: "#0f172a",
            noteTextColor: "#e5e7eb"
        }
    });
});
</script>

2.3. Per-Diagram Init Block

Each diagram can override settings using an init block:

%%{init:{"theme":"dark"}}%%

Example with a flowchart:

%%{init:{"theme":"dark"}}%% flowchart LR A[Start] --> B{Decision?} B -->|Yes| C[Continue] B -->|No| D[Stop]

3. DIAGRAM TYPES AND EXAMPLES

3.1. Flowchart

%%{init:{"theme":"dark"}}%% flowchart LR A[Start] --> B{Decision?} B -->|Yes| C[Continue] B -->|No| D[Stop]

3.2. Sequence Diagram

%%{init:{"theme":"dark","sequence":{"showSequenceNumbers":true}}}%% sequenceDiagram actor User participant Browser participant Server User->>Browser: Open page Browser->>Server: Request data Server-->>Browser: JSON response Browser-->>User: Render UI

3.3. Class Diagram

%%{init:{"theme":"dark"}}%% classDiagram class User { +string name +login() } class Session { +string token } User --> Session : creates

3.4. State Diagram

%%{init:{"theme":"dark"}}%% stateDiagram-v2 [*] --> Idle Idle --> Running : start() Running --> Idle : stop()

3.5. ER Diagram

%%{init:{"theme":"dark"}}%% erDiagram USER ||--o{ ORDER : places ORDER ||--|{ ITEM : contains

3.6. Journey Diagram

%%{init:{"theme":"dark"}}%% journey title User Journey section Discover Finds site: 4 Reads docs: 5 section Use Tries feature: 3 Fixes error: 2

3.7. Gantt Chart

%%{init:{"theme":"dark","gantt":{"axisFormat":"%b %d"}}}%% gantt dateFormat YYYY-MM-DD title Project Plan section Phase 1 Setup :done, p1, 2024-01-01, 3d Build :active, p2, 2024-01-04, 5d

3.8. Pie Chart

%%{init:{"theme":"dark","pie":{"textPosition":0.75}}}%% pie showData title Usage Breakdown "Docs" : 40 "UI" : 30 "Backend" : 20 "Other" : 10

3.9. Timeline

%%{init:{"theme":"dark"}}%% timeline title Release Timeline 2024-01 : Alpha 2024-03 : Beta 2024-06 : Launch

3.10. Mindmap

%%{init:{"theme":"dark"}}%% mindmap root((Project)) Planning Research Requirements Build Frontend Backend Deploy Testing Release

4. BEST PRACTICES

• Keep each diagram focused on a single idea.
• Use consistent naming across diagrams (same concept, same label).
• Prefer smaller diagrams over giant, unreadable ones.
• Put complex diagrams in their own sections or pages.
• Use per-diagram init blocks for local overrides instead of changing global config constantly.
• Validate the JSON in your %%{init:{...}}%% block if something breaks.

Dynamic content tip: If you inject diagrams dynamically (e.g., SPA, PWA), call: mermaid.run(); after the new content is added to the DOM.

5. QUICK REFERENCE CHEAT SHEET

Core diagram keywords:

• flowchart LR
• sequenceDiagram
• classDiagram
• stateDiagram-v2
• erDiagram
• journey
• gantt
• pie
• timeline
• mindmap

Common patterns:

Init block (first line): %%{init:{"theme":"dark"}}%%

HTML wrapper: <div class="mermaid"><!-- diagram code --></div>

Global init in JS: mermaid.initialize({ startOnLoad: true, theme: "dark" });

6. HOW TO USE THIS MANUAL

• As a book chapter: Each major section can become its own subchapter.
• As a reference: Paste directly into your docs or PWA and adjust labels only.
• As a teaching aid: Show the text, then show the rendered diagram side-by-side.
• As a template library: Copy these diagrams and evolve them for your own system.

End of mermaid_reference_manual.html