Diagrams with Mermaid

What are Mermaid diagrams?

Mermaid is a syntax similar to Markdown where you can use text to describe and automatically generate diagrams. With Mermaid, you can generate Flow charts, UML diagrams, Pie charts, Gantt diagrams, Entity Relationship diagrams, and more.

An Entity Relationship diagram example

Using Mermaid in your blog post

Heine sends an explicit :::render request to the configured Mermaid profile at build time. The profile fixes the command and selects the forest SVG for light mode and the dark SVG for dark mode, so the diagram source does not need a theme-specific init directive and the browser runs no Mermaid JavaScript.

Basic usage

:::render[mermaid alt="A concise description of the diagram" class="diagram"]
%%{init: {"layout": "dagre", "look": "classic", "flowchart": {"useMaxWidth": false}}}%%
flowchart TD
    A[Start] --> B[Finish]
:::

Replace the body with Mermaid source and provide alternative text that explains the diagram for readers who cannot see it. class="diagram" is optional, but this site uses it for responsive sizing.

Configuration belongs to the profile

The renderer profile in heine.toml owns the Mermaid executable, timeout, cache identity, and light and dark command arguments. The init directive above fixes the diagram's Dagre layout, Mermaid's non-shadow classic look, and its intrinsic width. flowchart owns the width setting for flowcharts; use "er": {"useMaxWidth": false} for entity-relationship diagrams. It does not choose colours, because the profile already selects the light and dark themes.

Explaining Mermaid diagram code

Here is how the diagram rendered above is embedded in this blog post as a code block. Fenced code stays literal, so it needs no escaping.

:::render[mermaid alt="Entity relationship diagram" class="diagram"]
%%{init: {"layout": "dagre", "look": "classic", "er": {"useMaxWidth": false}}}%%
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }
:::