Mermaid Extension for odoc

This extension adds support for Mermaid diagrams in odoc documentation. Mermaid is a JavaScript-based diagramming tool that renders Markdown-inspired text definitions into diagrams.

Installation

opam install odoc-mermaid-extension

Once installed, the extension is automatically loaded by odoc.

Usage

Use the {@mermaid[...]} tag to embed Mermaid diagrams:

{@mermaid[
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[Cancel]
]}

Examples

Flowchart

graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[Car]

Sequence Diagram

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

State Diagram

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Class Diagram

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }

Entity Relationship Diagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Gantt Chart

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2024-01-01, 30d
    Another task     :after a1, 20d
    section Another
    Task in sec      :2024-01-12, 12d
    another task     :24d

Options

The extension supports the following options:

theme - Mermaid theme: default, forest, dark, neutral
width - CSS width (e.g., 500px, 100%)
height - CSS height
format - Output format: omit for client-side JS, or png/svg for server-side rendering (requires mmdc CLI tool)

Theme Example

{@mermaid theme=forest[
graph LR
    A --> B --> C
]}

graph LR
    A --> B --> C

How It Works

By default, diagrams are rendered client-side using the Mermaid JavaScript library loaded from a CDN. The extension injects the necessary <script> tags into the HTML output.

For server-side rendering (useful for PDF generation or environments without JavaScript), install the mmdc CLI tool and use format=png or format=svg.