Creating Beautiful Diagrams with Mermaid in Markdown (MkDocs)¶

Objective: Master the art of creating dynamic, beautiful diagrams with Mermaid directly in your Markdown files, eliminating the need for static images and external diagramming tools.

Mermaid is a lightweight diagramming and charting tool that turns text into beautiful diagrams. It integrates seamlessly with MkDocs (especially when using the Material for MkDocs theme) and allows you to embed diagrams directly inside your Markdown files.

Instead of exporting static images, you define diagrams as code blocks and let Mermaid render them dynamically in your site.

1) Enabling Mermaid in MkDocs¶

Install Material for MkDocs (Recommended)¶

pip install mkdocs-material

Why: Material for MkDocs provides the best Mermaid integration with proper syntax highlighting and rendering.

Configure mkdocs.yml¶

# mkdocs.yml
markdown_extensions:
  - admonition
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.details
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Why: This configuration tells MkDocs to recognize fenced code blocks marked as mermaid and render them as interactive diagrams.

2) Your First Mermaid Diagram¶

Basic Flowchart¶

graph TD
    A[Start] --> B{Is MkDocs installed?}
    B -- Yes --> C[Install Material Theme]
    B -- No --> D[Install MkDocs First]
    C --> E[Enable Mermaid]
    D --> E
    E --> F[Profit!]

The Magic: This simple text becomes a beautiful, interactive flowchart. No external tools, no image files, just clean Markdown.

Understanding the Syntax¶

graph TD
    A[Start] --> B{Decision}
    B -- Yes --> C[Action 1]
    B -- No --> D[Action 2]
    C --> E[End]
    D --> E

Key Elements: - graph TD = Top-Down direction - [Text] = Rectangle nodes - {Text} = Diamond decision nodes - --> = Arrows connecting nodes - -- Label --> = Labeled arrows

3) Common Diagram Types¶

Flowcharts¶

flowchart LR
    A[User] --> B((MkDocs))
    B --> C{Markdown}
    C -->|Processed| D[Static Site]
    C -->|With Mermaid| E[Interactive Diagrams]
    E --> F[Beautiful Docs]

Why Flowcharts Work: Perfect for showing processes, workflows, and decision trees. The flowchart syntax is more modern than graph.

Sequence Diagrams¶

sequenceDiagram
    participant U as User
    participant B as Browser
    participant S as MkDocs Server

    U->>B: Request page
    B->>S: Fetch Markdown
    S-->>B: Rendered HTML + Mermaid
    B-->>U: Display site with diagrams

Why Sequence Diagrams Matter: Essential for showing interactions between systems, APIs, and user flows.

Class Diagrams¶

classDiagram
    class Postgres {
        +query(sql)
        +insert(data)
        +update(data)
        +delete(data)
    }
    class FDW {
        +connect()
        +scan()
        +filter()
    }
    class ParquetS3FDW {
        +read_parquet()
        +list_files()
    }
    Postgres <|-- FDW
    FDW <|-- ParquetS3FDW

Why Class Diagrams Help: Perfect for documenting system architecture, database relationships, and API structures.

State Diagrams¶

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
    Published --> Archived
    Archived --> [*]

    Draft --> Draft : Edit
    Review --> Draft : Reject
    Review --> Published : Approve
    Published --> Draft : Update

Why State Diagrams Are Powerful: Essential for showing system states, workflow stages, and lifecycle management.

Gantt Charts¶

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Research           :done,    des1, 2024-01-01, 2024-01-07
    Design            :active,  des2, 2024-01-08, 2024-01-14
    section Phase 2
    Development       :         des3, 2024-01-15, 2024-01-28
    Testing          :         des4, 2024-01-29, 2024-02-04
    section Phase 3
    Deployment        :         des5, 2024-02-05, 2024-02-11

Why Gantt Charts Matter: Perfect for project planning, timeline visualization, and milestone tracking.

Pie Charts¶

pie title Data Sources
    "PostgreSQL" : 45
    "Parquet Files" : 30
    "APIs" : 15
    "Other" : 10

Why Pie Charts Work: Great for showing proportions, data distribution, and resource allocation.

4) Advanced Styling and Customization¶

Custom Node Styling¶

graph TD
    A[Start]:::highlight --> B[Process]:::warning
    B --> C[End]:::success

    classDef highlight fill:#f96,stroke:#333,stroke-width:2px
    classDef warning fill:#ffa,stroke:#f66,stroke-width:2px
    classDef success fill:#9f9,stroke:#333,stroke-width:2px

Why Styling Matters: Visual hierarchy and color coding make diagrams more readable and professional.

Complex Flowcharts¶

flowchart TD
    A[User Request] --> B{Authentication}
    B -->|Valid| C[Process Request]
    B -->|Invalid| D[Return Error]
    C --> E{Data Source}
    E -->|Database| F[Query DB]
    E -->|File| G[Read File]
    E -->|API| H[Call API]
    F --> I[Format Response]
    G --> I
    H --> I
    I --> J[Return Data]
    D --> K[End]
    J --> K

Why Complex Diagrams Help: Real-world systems are complex. Mermaid handles the complexity while keeping the syntax simple.

Subgraphs and Grouping¶

flowchart TD
    subgraph "Frontend"
        A[React App]
        B[API Client]
    end
    subgraph "Backend"
        C[FastAPI]
        D[Database]
    end
    subgraph "Storage"
        E[S3]
        F[Parquet Files]
    end

    A --> B
    B --> C
    C --> D
    C --> E
    E --> F

Why Subgraphs Matter: Grouping related components makes complex architectures understandable.

5) Embedding in Tabs and Sections¶

Multi-View Examples¶

FlowchartSequenceClass Diagram

flowchart LR
    A[Input] --> B[Process]
    B --> C[Output]

sequenceDiagram
    A->>B: Request
    B-->>A: Response

classDiagram
    class A {
        +method1()
    }
    class B {
        +method2()
    }
    A --> B

Why Tabs Work: Different diagram types for different perspectives on the same system.

Admonition Integration¶

System Architecture

graph TD
    A[Client] --> B[Load Balancer]
    B --> C[API Gateway]
    C --> D[Microservices]
    D --> E[Database]

Why Admonitions Help: Contextual diagrams with explanations make documentation more engaging.

6) Real-World Examples¶

Database Architecture¶

erDiagram
    USERS ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_ITEMS : contains
    PRODUCTS ||--o{ ORDER_ITEMS : "ordered in"

    USERS {
        int id PK
        string name
        string email
        timestamp created_at
    }

    ORDERS {
        int id PK
        int user_id FK
        decimal total
        timestamp created_at
    }

    PRODUCTS {
        int id PK
        string name
        decimal price
        int stock
    }

    ORDER_ITEMS {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal price
    }

Why ER Diagrams Matter: Essential for database design, relationship documentation, and system understanding.

API Flow¶

sequenceDiagram
    participant C as Client
    participant L as Load Balancer
    participant A as API Gateway
    participant S as Service
    participant D as Database

    C->>L: HTTP Request
    L->>A: Forward Request
    A->>A: Authenticate
    A->>S: Route to Service
    S->>D: Query Database
    D-->>S: Return Data
    S-->>A: Process Response
    A-->>L: Return Response
    L-->>C: HTTP Response

Why API Flows Help: Understanding request/response cycles is crucial for debugging and optimization.

Deployment Pipeline¶

flowchart LR
    A[Code Commit] --> B[CI/CD Pipeline]
    B --> C{Tests Pass?}
    C -->|Yes| D[Build Image]
    C -->|No| E[Notify Developer]
    D --> F[Push to Registry]
    F --> G[Deploy to Staging]
    G --> H{Staging Tests?}
    H -->|Pass| I[Deploy to Production]
    H -->|Fail| J[Rollback]
    I --> K[Monitor]
    E --> L[End]
    J --> L
    K --> L

Why Deployment Diagrams Matter: Understanding deployment processes is essential for DevOps and reliability.

7) Performance and Best Practices¶

Optimizing Large Diagrams¶

graph TD
    subgraph "Data Layer"
        A[PostgreSQL]
        B[Redis Cache]
        C[S3 Storage]
    end
    subgraph "Application Layer"
        D[API Services]
        E[Background Jobs]
        F[Webhooks]
    end
    subgraph "Presentation Layer"
        G[Web App]
        H[Mobile App]
        I[Admin Panel]
    end

    G --> D
    H --> D
    I --> D
    D --> A
    D --> B
    D --> C
    E --> A
    F --> D

Why Structure Matters: Well-organized diagrams are easier to understand and maintain.

Responsive Design¶

graph LR
    A[Very Long Node Name] --> B[Another Long Node]
    B --> C[Yet Another Long Node Name]
    C --> D[Final Long Node]

Literal code example¶

<div style="overflow-x: auto;">
  <!-- Place a Mermaid fence here; example:
  ```mermaid
  graph LR
      A[Very Long Node Name] --> B[Another Long Node]
      B --> C[Yet Another Long Node Name]
      C --> D[Final Long Node]
  ```
  -->
</div>

Why Responsive Design Helps: Ensures diagrams work on all screen sizes and devices.

8) Troubleshooting Common Issues¶

Blank Diagrams¶

Problem: Diagrams appear as blank code blocks.

Solution: Ensure pymdownx.superfences is properly configured in mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Local Preview Issues¶

Problem: Diagrams don't render in local development.

Solution: 1. Run mkdocs serve and refresh the page 2. Clear browser cache 3. Check browser console for JavaScript errors

Diagram Too Wide¶

Problem: Diagrams extend beyond page width.

Solution: Wrap in a scrollable container:

graph LR
    A --> B --> C --> D --> E --> F --> G --> H --> I --> J

Literal code example¶

<div style="overflow-x: auto;">
  <!-- Place a Mermaid fence here; example:
  ```mermaid
  graph LR
      A --> B --> C --> D --> E --> F --> G --> H --> I --> J
  ```
  -->
</div>