Diagrams

MkDocs supports multiple diagram types through Mermaid and PlantUML integration, allowing you to create professional diagrams directly in your Markdown files.

Overview

Our documentation supports:

• Mermaid Diagrams - Flowcharts, sequence diagrams, state diagrams, and more
• PlantUML Diagrams - UML diagrams, network diagrams, and architectural diagrams
• Interactive Features - Zoom, pan, and full-screen viewing via lightbox
• Dark Mode Support - Diagrams adapt to your theme preference
• Export Options - Download diagrams as SVG or PNG

Mermaid Diagrams

Mermaid support is built-in through SuperFences. Create diagrams using simple text syntax:

Flowcharts

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]
```

Sequence Diagrams

sequenceDiagram
    participant User
    participant Browser
    participant Server
    participant Database

    User->>Browser: Enter URL
    Browser->>Server: HTTP Request
    Server->>Database: Query Data
    Database-->>Server: Return Results
    Server-->>Browser: HTTP Response
    Browser-->>User: Display Page

State Diagrams

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : Start Job
    Processing --> Success : Complete
    Processing --> Error : Fail
    Success --> [*]
    Error --> Idle : Retry
    Error --> [*] : Give Up

Class Diagrams

classDiagram
    class Animal {
        +String name
        +int age
        +void eat()
        +void sleep()
    }
    class Dog {
        +String breed
        +void bark()
    }
    class Cat {
        +String color
        +void meow()
    }
    Animal <|-- Dog
    Animal <|-- Cat

Entity Relationship Diagrams

erDiagram
    Customer ||--o{ Order : places
    Customer {
        int id PK
        string name
        string email
    }
    Order ||--|{ OrderItem : contains
    Order {
        int id PK
        date orderDate
        string status
    }
    OrderItem {
        int id PK
        int quantity
        float price
    }
    Product ||--o{ OrderItem : "ordered in"
    Product {
        int id PK
        string name
        float price
    }

Gantt Charts

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements    :done,    des1, 2024-01-01, 2024-01-07
    Design          :active,  des2, 2024-01-08, 5d
    section Development
    Backend         :         dev1, after des2, 10d
    Frontend        :         dev2, after des2, 12d
    section Testing
    Unit Tests      :         test1, after dev1, 3d
    Integration     :         test2, after dev2, 4d

Pie Charts

pie title Language Distribution
    "Python" : 45
    "JavaScript" : 30
    "Go" : 15
    "Other" : 10

Git Graphs

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature-1
    checkout feature-1
    commit
    commit
    checkout develop
    merge feature-1
    checkout main
    merge develop
    commit tag: "v1.0.0"

PlantUML Diagrams

PlantUML diagrams are supported through the Kroki plugin, providing access to comprehensive UML diagramming capabilities.

Configuration

PlantUML is configured via Kroki in mkdocs.yml:

plugins:
  - kroki:
      ServerURL: https://kroki.io
      EnablePlantUML: true
      HttpMethod: POST
      FileTypes:
        - svg
        - png

Activity Diagrams

@startuml
start
:Initialize Process;
:Read Input Data;
if (Data Valid?) then (yes)
  :Process Data;
  :Generate Report;
else (no)
  :Log Error;
  :Send Alert;
endif
:Cleanup;
stop
@enduml

Use Case Diagrams

@startuml
left to right direction
actor User
actor Admin

rectangle "Blog System" {
  User --> (Read Posts)
  User --> (Comment)
  User --> (Search)

  Admin --> (Write Posts)
  Admin --> (Moderate Comments)
  Admin --> (Manage Users)

  (Write Posts) ..> (Upload Images) : include
  (Moderate Comments) ..> (Delete Comment) : extend
}
@enduml

Component Diagrams

@startuml
package "Frontend" {
  [React App]
  [Redux Store]
  [API Client]
}

package "Backend" {
  [REST API]
  [Auth Service]
  [Business Logic]
}

database "PostgreSQL" {
  [Users Table]
  [Posts Table]
}

[React App] --> [Redux Store]
[React App] --> [API Client]
[API Client] --> [REST API]
[REST API] --> [Auth Service]
[REST API] --> [Business Logic]
[Business Logic] --> [PostgreSQL]
@enduml

Network Diagrams

@startuml
!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.4.0
!includeurl ICONURL/common.puml
!includeurl ICONURL/devicons2/nginx_original.puml
!includeurl ICONURL/devicons2/docker.puml
!includeurl ICONURL/devicons2/postgresql.puml

DEV_NGINX(proxy, "Nginx\nLoad Balancer")
DEV_DOCKER(app1, "App Server 1")
DEV_DOCKER(app2, "App Server 2")
DEV_POSTGRESQL(db, "Database")

proxy --> app1
proxy --> app2
app1 --> db
app2 --> db
@enduml

Image Galleries

Display multiple diagrams or images in a responsive gallery layout with lightbox support.

Basic Image Gallery

System Architecture Overview

Data Flow Diagram

Deployment Architecture

Diagram Gallery

You can create galleries of diagrams generated from Mermaid or PlantUML:

User Flow

graph LR
    A[User] --> B[Login]
    B --> C{Authenticated?}
    C -->|Yes| D[Dashboard]
    C -->|No| B

Database Schema

erDiagram
    User ||--o{ Post : writes
    Post ||--o{ Comment : has
    User ||--o{ Comment : writes

Lightbox Integration

All images and diagrams support lightbox functionality for full-screen viewing:

• Click any image to open in lightbox
• Navigate between images with arrow keys
• Zoom with scroll or pinch gestures
• Close with ESC or click outside

Image with Caption

{: .lightbox caption="Complete system architecture showing all components and their interactions"}

Excluding from Lightbox

Add the no-lightbox class to exclude specific images:

<img loading="lazy" src="../assets/images/icon.png" alt="Static Icon">{: .no-lightbox}

Advanced Features

Dark Mode Support

Diagrams automatically adapt to your theme preference:

%%{init: {'theme':'neutral'}}%%
graph TD
    A[Auto Theme] --> B{Dark Mode?}
    B -->|Yes| C[Dark Colors]
    B -->|No| D[Light Colors]

Responsive Diagrams

All diagrams are responsive and scale appropriately:

/* Automatically applied */
.mermaid svg,
.kroki-diagram svg {
  max-width: 100%;
  height: auto;
}

Export Options

Diagrams can be exported in various formats:

1. Right-click on any diagram
2. Select "Save image as..."
3. Choose format (SVG or PNG)

Performance Optimization

Lazy Loading

Large diagrams are lazy-loaded to improve page performance:

<img loading="lazy" src="../assets/images/complex-diagram.png" alt="Large Diagram">{: loading="lazy"}

Caching

Kroki diagrams are cached to reduce server load:

• First render: Generated from source
• Subsequent views: Served from cache
• Cache duration: 24 hours

Best Practices

1. Choose the Right Diagram Type

Use Case	Mermaid	PlantUML
Simple flowcharts	✓	✓
Sequence diagrams	✓	✓
UML diagrams	Limited	✓
Network diagrams	-	✓
Gantt charts	✓	✓
Mind maps	✓	✓

2. Accessibility

Always provide alternative text:

```mermaid
graph LR
    A --> B

```

3. Mobile Optimization

Keep diagrams simple for mobile viewing:

• Limit nodes to 5-7 per diagram
• Use short, clear labels
• Avoid complex branching

4. Consistent Styling

Maintain visual consistency across all diagrams:

• Use the same color scheme
• Consistent node shapes
• Uniform text sizing

Troubleshooting

Mermaid Not Rendering

1. Check browser console for errors
2. Verify Mermaid.js is loaded
3. Validate diagram syntax

PlantUML/Kroki Issues

1. Check server connectivity
2. Verify plugin configuration
3. Test with simple diagram first

Lightbox Not Working

1. Ensure GLightbox is enabled
2. Check for JavaScript errors
3. Verify image paths are correct

Examples Gallery

Explore our comprehensive diagram examples showcasing all supported diagram types with full source code.

Related Documentation

• SuperFences - Enhanced code blocks
• Mathematical Notation - LaTeX math support
• Code Blocks - Syntax highlighting