Using Mermaid Diagrams in Documentation#

Overview#

Loreax wiki documentation supports Mermaid.js (v11.4.0) for rendering flowcharts, sequence diagrams, and other visual diagrams directly in markdown.

Mermaid diagrams automatically adapt to the documentation theme (dark/light mode) and re-render when you switch themes.

Supported Diagram Types#

Mermaid supports many diagram types. The most commonly used in Loreax documentation:

• Flowcharts — Workflow and process flows
• Sequence Diagrams — API interactions and message flows
• State Diagrams — State machine transitions
• Entity Relationship Diagrams — Database schema relationships
• Gantt Charts — Timeline and scheduling
• Git Graphs — Git branching and merging flows

Basic Syntax#

Flowchart Example#

flowchart TD
    A[User Request] --> B{Authenticated?}
    B -- Yes --> C[Process Request]
    B -- No --> D[Return 401]
    C --> E[Return 200]

Markdown code:

```mermaid
flowchart TD
    A[User Request] --> B{Authenticated?}
    B -- Yes --> C[Process Request]
    B -- No --> D[Return 401]
    C --> E[Return 200]
```

Sequence Diagram Example#

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database
    
    C->>A: POST /v1/posts
    A->>D: Create post record
    D-->>A: Post created
    A->>D: Dispatch job
    A-->>C: 201 Created

Markdown code:

```mermaid
sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database
    
    C->>A: POST /v1/posts
    A->>D: Create post record
    D-->>A: Post created
    A->>D: Dispatch job
    A-->>C: 201 Created
```

State Diagram Example#

stateDiagram-v2
    [*] --> Draft
    Draft --> Processing: Publish
    Processing --> Published: Success
    Processing --> Failed: Error
    Failed --> Draft: Retry
    Published --> Archived
    Archived --> [*]

Markdown code:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Processing: Publish
    Processing --> Published: Success
    Processing --> Failed: Error
    Failed --> Draft: Retry
    Published --> Archived
    Archived --> [*]
```

Entity Relationship Diagram Example#

erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ MEDIA : contains
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    
    USER {
        ulid id PK
        string email
        string handle
    }
    
    POST {
        ulid id PK
        ulid creator_id FK
        string title
        text body
    }

Markdown code:

```mermaid
erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ MEDIA : contains
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    
    USER {
        ulid id PK
        string email
        string handle
    }
    
    POST {
        ulid id PK
        ulid creator_id FK
        string title
        text body
    }
```

Flowchart Node Types#

Shapes#

flowchart LR
    A[Rectangle]
    B(Rounded Rectangle)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G>Asymmetric]
    H{Diamond}
    I{{Hexagon}}
    J[/Parallelogram/]
    K[\Parallelogram Alt\]
    L[/Trapezoid\]
    M[\Trapezoid Alt/]

Direction#

• flowchart TD — Top to bottom (default)
• flowchart LR — Left to right
• flowchart RL — Right to left
• flowchart BT — Bottom to top

Arrows and Connections#

flowchart LR
    A --> B
    C -.-> D
    E ==> F
    G -- Label --> H
    I -. Dotted .-> J
    K == Bold ==> L
    M -->|Label| N

Arrow types:

• --> — Solid arrow
• -.-> — Dotted arrow
• ==> — Bold arrow
• -- text --> — Arrow with label
• -->|text| — Arrow with label (alternate syntax)

Best Practices#

1. Keep Diagrams Focused#

Good:

flowchart TD
    A[Login] --> B{Valid?}
    B -- Yes --> C[Success]
    B -- No --> D[Error]

Avoid: Cramming 20+ nodes into one diagram. Break complex flows into multiple smaller diagrams.

2. Use Descriptive Labels#

Good:

flowchart TD
    A[User uploads file] --> B{File size < 50MB?}
    B -- Yes --> C[Process upload]
    B -- No --> D[Return 413 Payload Too Large]

Avoid:

flowchart TD
    A[A] --> B{B?}
    B -- Y --> C[C]
    B -- N --> D[D]

3. Consistent Formatting#

• Use UPPERCASE for entity names in ERDs
• Use consistent verb tense (present: "Process", not "Processing")
• Align diagram direction with reading flow (LR for horizontal processes, TD for hierarchies)

4. Add Context#

Always include a text explanation before or after the diagram:

The media processing pipeline follows these steps:

[mermaid diagram]

Each processor runs asynchronously via queue jobs to avoid blocking the HTTP request.

Theme Adaptation#

Mermaid diagrams automatically adapt to the wiki theme:

• Dark mode: Blue accents (#3b82f6), dark backgrounds, light text
• Light mode: Darker blue (#2563eb), light backgrounds, dark text

Switching themes re-renders all diagrams instantly — no page reload needed.

Common Use Cases in Loreax Docs#

Domain Workflows#

Use flowcharts to show high-level flows:

flowchart TD
    A[User Request] --> B[RankingService]
    B --> C[Load Signals]
    C --> D{Has Affinity?}
    D -- Yes --> E[Apply User Signals]
    D -- No --> F[Apply Cold Start]
    E --> G[Sort by Score]
    F --> G
    G --> H[Return Ranked Posts]

API Interactions#

Use sequence diagrams for multi-step API flows:

sequenceDiagram
    participant C as Client
    participant A as API
    participant L as Ledger
    participant M as MPESA
    
    C->>A: POST /v1/payments/top-up
    A->>L: Check balance
    L-->>A: Current balance
    A->>M: Initiate STK Push
    M-->>C: STK Prompt
    C->>M: Enter PIN
    M->>A: Callback (success)
    A->>L: Post transaction
    L-->>A: Updated balance
    A-->>C: 200 OK

State Transitions#

Use state diagrams for status workflows:

stateDiagram-v2
    [*] --> Draft
    Draft --> Pending: Submit
    Pending --> Approved: Approve
    Pending --> Rejected: Reject
    Approved --> Published: Publish
    Rejected --> Draft: Edit
    Published --> [*]

Troubleshooting#

Diagram Not Rendering#

Symptom: Code block shows raw text instead of rendered diagram

Cause: Missing mermaid language tag

Fix:

```mermaid
flowchart TD
    A --> B
```

Syntax Error#

Symptom: Diagram shows "Syntax Error" message

Cause: Invalid Mermaid syntax

Fix: Check Mermaid documentation for correct syntax. Common errors:

• Missing semicolons in complex diagrams
• Invalid node IDs (must start with letter, no spaces)
• Mismatched arrow types

Example error:

flowchart TD
    A Node --> B  # ❌ Spaces in node ID

Fixed:

flowchart TD
    A[Node] --> B  # ✅ Brackets for labels with spaces

Theme Colors Not Matching#

Symptom: Diagram colors don't match dark/light theme

Cause: Browser cache or theme switch didn't trigger re-render

Fix: Hard refresh (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)

Further Reading#

• Official Mermaid Documentation
• Mermaid Live Editor — Test diagrams interactively
• Flowchart Syntax
• Sequence Diagram Syntax
• State Diagram Syntax

Examples in Loreax Docs#

See these wiki pages for real-world examples:

• Media Processing — Complex media processing workflows
• Payments — MPESA integration flows
• Identity — Authentication and MFA flows
• Discovery README — Ranking pipeline

Technical Implementation#

Mermaid.js is loaded as an ES module from jsDelivr CDN (v11.4.0). The integration:

1. Converts markdown code blocks — <code class="language-mermaid"> elements are automatically converted to <div class="mermaid"> on page load
2. Initializes Mermaid — Configured with theme-aware colors matching the documentation theme
3. Handles theme switching — Re-renders all diagrams when switching between dark/light modes
4. Stores diagram source — Original mermaid code is preserved in data-mermaid-source attribute for re-rendering

Browser requirements: Modern browsers with ES6 module support (Chrome 61+, Firefox 60+, Safari 10.1+, Edge 16+).