Mermaid diagrams

Mermaid lets you describe diagrams in plain text and renders them as SVG in the browser. aphid recognises fenced code blocks tagged mermaid and emits them as <pre class="mermaid"> elements; the bundled runtime turns them into diagrams once the page loads.

This page is a quick tour of the diagram types you’ll reach for most often. For the full catalogue and every option each diagram supports, see the Mermaid documentation.

Note

The runtime is loaded on demand: pages without a mermaid block don’t include the script. See Markdown for how the build pipeline handles this, and Themes for what base.html needs to wire up in a custom theme.

Flowchart

The most common diagram type — boxes and arrows. The first token after flowchart is the direction (TD top-down, LR left-right, BT, RL).

```mermaid
flowchart LR
    A[Markdown file] --> B{Has frontmatter?}
    B -- yes --> C[Parse YAML]
    B -- no --> D[Skip]
    C --> E[Render to HTML]
    D --> E
```

flowchart LR
    A[Markdown file] --> B{Has frontmatter?}
    B -- yes --> C[Parse YAML]
    B -- no --> D[Skip]
    C --> E[Render to HTML]
    D --> E

Node shapes ([] rectangle, () rounded, {} diamond, (()) circle, …) and edge styles (-->, -.->, ==>) are documented in the flowchart syntax reference.

Sequence diagram

Useful for protocols, request/response flows, and any time-ordered interaction between actors.

```mermaid
sequenceDiagram
    participant Browser
    participant aphid
    participant Mermaid
    Browser->>aphid: GET /wiki/mermaid/
    aphid-->>Browser: HTML + <pre class="mermaid">
    Browser->>Mermaid: parse blocks
    Mermaid-->>Browser: SVG
```

sequenceDiagram
    participant Browser
    participant aphid
    participant Mermaid
    Browser->>aphid: GET /wiki/mermaid/
    aphid-->>Browser: HTML + <pre class="mermaid">
    Browser->>Mermaid: parse blocks
    Mermaid-->>Browser: SVG

Arrow forms (->> solid, -->> dashed, -) async) and groupings (alt, loop, par, note over) are covered in the sequence diagram reference.

Class diagram

For data models and type relationships.

```mermaid
classDiagram
    class Page~F~ {
        +String slug
        +String body
        +F frontmatter
        +url_path() String
    }
    class BlogFrontmatter {
        +String title
        +Date created
        +Vec~Tag~ tags
    }
    class WikiFrontmatter {
        +String title
        +Option~String~ category
    }
    Page <|-- BlogFrontmatter : F =
    Page <|-- WikiFrontmatter : F =
```

classDiagram
    class Page~F~ {
        +String slug
        +String body
        +F frontmatter
        +url_path() String
    }
    class BlogFrontmatter {
        +String title
        +Date created
        +Vec~Tag~ tags
    }
    class WikiFrontmatter {
        +String title
        +Option~String~ category
    }
    Page <|-- BlogFrontmatter : F =
    Page <|-- WikiFrontmatter : F =

Visibility markers (+, -, #), generics with ~T~, and relationship arrows (<|-- inheritance, *-- composition, o-- aggregation) are listed in the class diagram reference.

State diagram

For finite state machines and lifecycle flows.

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : start build
    Loading --> Indexed : pass 1 done
    Indexed --> Rendering : pass 2 starts
    Rendering --> Written : write dist/
    Written --> [*]
    Rendering --> Failed : error
    Failed --> [*]
```

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : start build
    Loading --> Indexed : pass 1 done
    Indexed --> Rendering : pass 2 starts
    Rendering --> Written : write dist/
    Written --> [*]
    Rendering --> Failed : error
    Failed --> [*]

Composite states, choice points, and forks/joins are described in the state diagram reference.

Entity-relationship diagram

For database schemas and domain models.

```mermaid
erDiagram
    POST ||--o{ TAG : "tagged with"
    POST }o--|| AUTHOR : "written by"
    POST {
        string slug PK
        string title
        date created
    }
    TAG {
        string slug PK
        string name
    }
    AUTHOR {
        string name PK
        string email
    }
```

erDiagram
    POST ||--o{ TAG : "tagged with"
    POST }o--|| AUTHOR : "written by"
    POST {
        string slug PK
        string title
        date created
    }
    TAG {
        string slug PK
        string name
    }
    AUTHOR {
        string name PK
        string email
    }

Cardinality markers (|| exactly one, o{ zero or more, |{ one or more) and attribute keys (PK, FK, UK) are detailed in the ER diagram reference.

Gantt chart

For project timelines and roadmaps.

```mermaid
gantt
    title aphid roadmap
    dateFormat YYYY-MM-DD
    section v0.1
    Core pipeline       :done, 2026-01-01, 2026-03-01
    Themes & templates  :done, 2026-03-01, 2026-04-15
    section v0.1.1
    Mermaid + alerts    :done, 2026-04-15, 2026-04-30
    section v0.2
    Drafts & RSS        :active, 2026-05-01, 30d
```

gantt
    title aphid roadmap
    dateFormat YYYY-MM-DD
    section v0.1
    Core pipeline       :done, 2026-01-01, 2026-03-01
    Themes & templates  :done, 2026-03-01, 2026-04-15
    section v0.1.1
    Mermaid + alerts    :done, 2026-04-15, 2026-04-30
    section v0.2
    Drafts & RSS        :active, 2026-05-01, 30d

Task states (done, active, crit), dependencies via after taskId, and milestones with :milestone, are in the Gantt reference.

Mindmap

Useful for hierarchical brainstorms.

```mermaid
mindmap
  root((aphid))
    Content
      Blog
      Wiki
      Pages
    Pipeline
      Pass 1: index
      Pass 2: render
    Output
      build → dist/
      serve → live reload
```

mindmap
  root((aphid))
    Content
      Blog
      Wiki
      Pages
    Pipeline
      Pass 1: index
      Pass 2: render
    Output
      build → dist/
      serve → live reload

Node shape syntax matches flowcharts ((()), [], {{}}, …). See the mindmap reference.

Theming

Diagram colours can be tuned per site by overriding themeVariables when calling mermaid.initialize in your theme’s base.html — see Themes for a worked example. The full set of theme variables is documented in the Mermaid theming guide.

Other diagram types

Mermaid also supports pie charts, quadrant charts, requirement diagrams, user journeys, gitgraph, C4 diagrams, timelines, sankey charts, XY charts, and block diagrams. They all use the same fenced-block mechanism — just change the first line. The Mermaid syntax index lists them all.