Skip to content
astro-mermaid-satteri

How It Works

Build time

Section titled “Build time”

At build time, a Sätteri hast plugin swaps <pre><code class="language-mermaid"> blocks for <pre class="mermaid"> elements containing the raw diagram text. It also excludes mermaid from syntax highlighting so Shiki doesn’t transform the block before the plugin sees it.

The same plugin parses info-string options — w-NNN, h-NNN, title="...", and align=... — and emits data-width, data-height, data-align attributes and an optional <figure>/<figcaption> wrapper.

Client side

Section titled “Client side”

The per-page script:

  1. Lazily imports mermaid (code-split, so it only loads on pages with diagrams).
  2. Loads any registered icon packs, then calls mermaid.initialize().
  3. Renders each pre.mermaid element, copying the SVG into it and adding a Copy button.
  4. Re-injects its CSS on astro:page-load, because View Transitions replace the <head>.

While diagrams render, a spinner shows in place of the unprocessed block, and a min-height on the container keeps the page from jumping.

Lazy loading

Section titled “Lazy loading”

Diagrams below the fold are deferred until they scroll near the viewport via an IntersectionObserver with a 300px root margin. Diagrams already rendered (e.g. during a theme switch) re-render immediately instead of going back through the observer.

View Transitions

Section titled “View Transitions”

The script re-runs on astro:page-load after a View Transition swap, so diagrams on the new page render and the CSS is re-injected. The data-theme MutationObserver is debounced to avoid double renders during the swap.