Mermaid¶

Mermaid is a JavaScript-based diagramming tool that lets you write diagrams using a simple, Markdown-friendly syntax. It renders diagrams directly in the browser, which makes it ideal for:

Flowcharts
Sequence diagrams
Gantt charts
State machines
Class diagrams
Entity-relationship diagrams

Because Mermaid runs client-side, it does not require any external services or preprocessing — the browser transforms the text into a diagram at page load.

High-Level Flowchart¶

flowchart TD
    A[Markdown + Diagrams] --> B[Docker Container];
    B --> C[MkDocs Builds];
    C --> D[Mermaid Rendered in Browser];
    C --> E[PlantUML Rendered by Java];
    D --> F[Final Static Website];
    E --> F[Final Static Website];

Detailed Pipeline Flow¶

flowchart TD
    subgraph Host["Host Machine"]
        M[Markdown + Assets]
    end

    subgraph Docker["Docker Container"]
        D1[mkdocs serve / build]
        D2[pymdownx.superfences]
        D3[mermaid.js]
        D4[plantuml-markdown]
        D5[java -jar plantuml.jar]
    end

    subgraph Output["Static Website"]
        O1[HTML Files]
        O2[SVG Diagrams]
        O3[Local Mermaid Rendering]
    end

    M -->|Bind Mount| D1
    D1 --> D2

    %% Mermaid path
    D2 -->|mermaid blocks| D3
    D3 --> O3

    %% PlantUML path
    D2 -->|plantuml blocks| D4
    D4 --> D5
    D5 --> O2

    D1 --> O1

Sequence Diagram¶

sequenceDiagram
    participant User as Developer
    participant Docker as Docker Container
    participant MkDocs as MkDocs Builder
    participant PUML as PlantUML<br/>Local Java
    participant Browser as Browser

    User->>Docker: docker compose up
    Docker->>MkDocs: Start live server
    MkDocs->>MkDocs: Load Markdown
    MkDocs->>MkDocs: Detect fenced code blocks

    MkDocs->>Browser: Mermaid blocks → left as-is
    Browser->>Browser: Render using mermaid.min.js

    MkDocs->>PUML: PlantUML blocks → request SVG
    PUML->>MkDocs: Return rendered SVG

    MkDocs->>Docker: Build HTML page
    Docker->>User: Serve at http://localhost:8000