skip to content

Diagrams with Mermaid


Write a diagram as text in a code fence labelled mermaid, in any .md or .mdx post. No import, no component, no build step. Pele draws it in the browser, in the site’s colours. The colours follow the theme through CSS variables, so switching between light and dark does not redraw the diagram.

```mermaid
flowchart LR
accTitle: Publishing a post
accDescr: Write a draft, preview it locally, then publish it.
A[Draft] --> B[Preview] --> C[Publish]
```
flowchart LR
accTitle: Publishing a post
accDescr: Write a draft, preview it locally, then publish it.
A[Draft] --> B[Preview] --> C[Publish]

Flowcharts

Use TD for top-down and LR for left-to-right. Square brackets make boxes, curly braces make decisions, and text between pipes labels an edge.

flowchart TD
accTitle: Deciding where a change goes
accDescr: A change that touches the theme goes upstream; anything else stays in the fork.
A[Make a change] --> B{Theme or content?}
B -->|Theme| C[Open a PR upstream]
B -->|Content| D[Commit to your fork]
C --> E[Pull the update into your fork]
D --> F[Deploy]
E --> F

Sequence diagrams

Good for requests, handshakes and anything else that happens in order between a few parties.

sequenceDiagram
accTitle: Loading a post with a diagram
accDescr: The browser loads the page, then fetches Mermaid only when a diagram scrolls near the viewport.
participant Browser
participant Site
Browser->>Site: Request post
Site-->>Browser: HTML
Note over Browser: Diagram in view
Browser->>Site: Request Mermaid
Site-->>Browser: Mermaid
Note over Browser: Draw diagram

State diagrams

stateDiagram-v2
accTitle: Lifecycle of a post
accDescr: A post starts as a draft, gets published, and can be updated any number of times.
[*] --> Draft
Draft --> Published: publish
Published --> Updated: edit
Updated --> Updated: edit

Entity relationships

erDiagram
accTitle: How posts and tags relate
accDescr: A post has many tags, and each tag has an archive page listing its posts.
POST }o--o{ TAG : "tagged with"
TAG ||--|| ARCHIVE : "lists posts on"
POST {
string title
date publishDate
date updatedDate
}
TAG {
string name
}

The fence still uses Mermaid syntax. Pele draws the diagram types built into Mermaid 12.1, including class diagrams, Gantt charts, pie charts, mind maps and git graphs. See the Mermaid documentation for the syntax.

How it loads

  • Only posts that contain a diagram include the loader script. Other posts ship no diagram code at all.
  • Pele is downloaded from the site’s own assets when the first diagram comes within 200px of the viewport, so a diagram at the bottom of a long post costs nothing until the reader gets near it.
  • Diagram source is excluded from site search, so the search index only holds the prose around it.

Writing good diagrams

  • Add accTitle and accDescr to every diagram. Screen readers read them in place of the drawing.
  • Keep diagrams narrow. Pele refits the layout to a phone screen; a drawing that is still wider scrolls sideways inside its frame.
  • Without JavaScript, or if the syntax is invalid, the source text stays on the page, so it should read sensibly on its own. Errors are logged to the browser console.