Adding Mermaid diagram support to an Astro blog

Mermaid lets you write diagrams as text: sequence diagrams, flowcharts, ER diagrams, rendered as SVG. For a technical blog that explains architectures and flows, being able to write diagrams in Markdown the same way you write code blocks is a significant quality-of-life improvement.

This post covers how I added Mermaid support to this blog, why I chose client-side rendering over a build-time rehype plugin, and the specific problems that came up along the way.

Architecture overview

The remark plugin handles everything at build time: it intercepts ```mermaid blocks before Expressive Code sees them and converts each one to a static HTML container. At runtime, the CDN-loaded Mermaid library reads each container’s data-mermaid attribute and replaces it with an SVG.

Why not a plugin?

The first-party options are rehype-mermaid and @beoe/rehype-mermaid. Both work: they process Mermaid blocks at build time and emit static SVG. The trade-off is that they require a headless browser (Playwright or Puppeteer) to render the SVG, which adds a heavy build dependency and complicates the Netlify build environment.

The client-side approach, installing the mermaid package and rendering on page load, is simpler, builds anywhere, and is fast enough for a blog. Mermaid is served from a CDN via a <script defer> tag, so nothing extra enters the Astro build pipeline.

Bypassing Expressive Code for mermaid blocks

This blog uses Expressive Code for syntax highlighting. EC processes every fenced code block, including ```mermaid, wrapping it in its own component output. That means the raw <pre><code class="language-mermaid"> element the client-side Mermaid renderer needs never makes it to the DOM.

EC has no built-in exclude list, so the solution is a small remark plugin that runs before EC in the pipeline, converting mermaid code nodes into raw HTML. The plugin stores the diagram definition in a data-mermaid attribute and injects a loading skeleton as the initial child:

1
function escapeAttr(str) {
2
  return str
3
    .replace(/&/g, '&')
4
    .replace(/"/g, '"')
5
    .replace(/</g, '&lt;')
6
    .replace(/>/g, '&gt;');
7
}
8

9
export function remarkMermaid() {
10
  return (tree) => {
11
    function walk(node, parent, index) {
12
      if (node.type === 'code' && node.lang === 'mermaid' && parent) {
13
        const titleMatch = node.meta?.match(/title="([^"]+)"/);
14
        const title = titleMatch?.[1] ?? null;
15
        parent.children[index] = {
16
          type: 'html',
17
          value:
18
            `<div class="mermaid-diagram" data-loading data-mermaid="${escapeAttr(node.value)}"` +
19
            (title ? ` data-title="${escapeAttr(title)}"` : '') +
20
            `>${SKELETON}</div>`,
21
        };
22
        return;
23
      }
24
      if (node.children) {
25
        node.children.forEach((child, i) => walk(child, node, i));
26
      }
27
    }
28
    walk(tree, null, null);
29
  };
30
}

Register it in astro.config.mjs. syntaxHighlight: false is also needed to prevent Astro’s built-in Shiki from conflicting with Expressive Code:

1
import { remarkMermaid } from './src/plugins/remark-mermaid.js';
2

3
export default defineConfig({
4
  markdown: {
5
    remarkPlugins: [remarkMermaid],
6
    syntaxHighlight: false,
7
  },
8
});

Because remark runs before rehype (where EC operates), mermaid blocks are already opaque HTML by the time EC processes the document. EC never sees them. The plugin emits the final container element at build time, storing the diagram definition as a data-mermaid attribute: no DOM manipulation is needed at runtime.

A loading skeleton while Mermaid initialises

SKELETON (defined at the top of the plugin file) is a string of HTML: an animated placeholder with three rows of nodes connected by vertical connectors. Here is the shape of what the plugin emits for each mermaid block:

1
<div class="mermaid-diagram" data-loading data-mermaid="sequenceDiagram...">
2
  <div class="mermaid-skeleton" aria-hidden="true">
3
    <div class="mermaid-skeleton__row"><!-- top node row --></div>
4
    <div class="mermaid-skeleton__connector"></div>
5
    <div class="mermaid-skeleton__row"><!-- middle nodes --></div>
6
    <div class="mermaid-skeleton__connector"></div>
7
    <div class="mermaid-skeleton__row"><!-- bottom nodes --></div>
8
  </div>
9
</div>

The CSS targets [data-loading] to show the shimmer animation and set color: transparent, which hides the definition text that briefly occupies the container between skeleton removal and SVG insertion:

1
:global(.mermaid-diagram[data-loading]) {
2
  color: transparent;
3
}

Because this HTML ships with the page, the skeleton is visible from the first paint, before any JavaScript runs. There is no blank space and no layout shift where the diagram will appear.

renderDiagrams() re-applies data-loading at the start of each call, so re-renders triggered by a theme change also show the skeleton rather than a flash of definition text. The attribute is removed after mermaid.run() resolves.

Installing and initialising Mermaid

1
pnpm add mermaid

In MarkdownPostLayout.astro, a <script> block handles the rendering. Astro bundles these component scripts automatically.

Only the type is imported from the package:

1
import type { MermaidConfig } from 'mermaid';

Mermaid itself is not imported as an ES module. A local type describes the slice of the API we use, and renderDiagrams() resolves the value from window.mermaid, polling every 10ms until it is available:

1
type MermaidApi = {
2
  initialize: (config: unknown) => void;
3
  run: (options: { nodes: Element[] }) => Promise<void>;
4
};
5

6
const mermaid = await new Promise<MermaidApi>((resolve) => {
7
  if (window.mermaid) { resolve(window.mermaid); return; }
8
  const id = setInterval(() => {
9
    if (window.mermaid) { clearInterval(id); resolve(window.mermaid); }
10
  }, 10);
11
});

This is necessary because Mermaid is loaded via a <script defer> tag: the CDN script may not have executed by the time the page’s own bundle runs.

startOnLoad: false in the config prevents Mermaid from scanning and rendering on DOMContentLoaded. The setup code needs to run first.

Reading definitions and preparing expand buttons

Because the remark plugin emits <div class="mermaid-diagram" data-loading data-mermaid="..."> containers with the definition stored as an attribute, the client-side setup is straightforward: query those containers, read each definition, create the expand button, and store everything in a Map keyed by the container element:

1
const definitions = new Map<HTMLElement, { definition: string; btn: HTMLButtonElement }>();
2

3
document
4
  .querySelectorAll<HTMLElement>('.post__content .mermaid-diagram[data-mermaid]')
5
  .forEach((container) => {
6
    const definition = container.dataset.mermaid!;
7

8
    const expandBtn = document.createElement('button');
9
    expandBtn.className = 'media-expand-btn';
10
    expandBtn.setAttribute('aria-label', 'View diagram fullscreen');
11

12
    definitions.set(container, { definition, btn: expandBtn });
13
  });

Storing the expand button alongside the definition avoids recreating it on every re-render: after mermaid.run() resolves, the existing button is simply re-appended to the updated container.

renderDiagrams reinitialises Mermaid with the current theme, restores the definition text into each container (which mermaid.run() replaces with SVG), then appends the button after rendering completes:

1
async function renderDiagrams() {
2
  const isDark = document.documentElement.dataset.theme === 'dark';
3
  mermaid.initialize(getMermaidConfig(isDark));
4

5
  definitions.forEach(({ definition }, container) => {
6
    container.removeAttribute('data-processed');
7
    container.setAttribute('data-loading', '');
8
    container.textContent = definition;
9
  });
10

11
  await mermaid.run({ nodes: [...definitions.keys()] });
12

13
  definitions.forEach(({ btn }, container) => {
14
    container.removeAttribute('data-loading');
15
    container.appendChild(btn);
16

17
    const svgEl = container.querySelector('svg');
18
    if (svgEl) {
19
      const titleText = container.dataset.title;
20
      if (titleText) {
21
        const titleId = `mermaid-title-${Math.random().toString(36).slice(2, 8)}`;
22
        const titleEl = document.createElementNS('http://www.w3.org/2000/svg', 'title');
23
        titleEl.id = titleId;
24
        titleEl.textContent = titleText;
25
        svgEl.prepend(titleEl);
26
        svgEl.setAttribute('role', 'img');
27
        svgEl.setAttribute('aria-labelledby', titleId);
28
      } else {
29
        svgEl.setAttribute('role', 'img');
30
        svgEl.setAttribute('aria-label', 'Diagram');
31
      }
32
    }
33
  });
34
}
35

36
await renderDiagrams();

Theming for light and dark mode

Mermaid bakes theme colours into the SVG at render time, so a CSS variable change alone won’t update an already-rendered diagram when the user switches themes. The right approach is to pass the correct theme at initialisation time, then re-run the whole render when the theme changes.

A helper function returns the config for the current theme. The Mermaid type import is used only for the return type: MermaidConfig keeps the theme property typed as "dark" | "default" | "base" | "forest" | "neutral" | "null", not a plain string:

1
import type { MermaidConfig } from 'mermaid';
2

3
const mermaidThemePalette = {
4
  dark: {
5
    primaryColor: '#3d1528',
6
    primaryTextColor: '#abb2bf',
7
    lineColor: '#767c89',
8
    secondaryColor: '#2c313a',
9
    titleColor: '#dcdcdc',
10
  },
11
  light: {
12
    primaryColor: '#fce8f2',
13
    primaryTextColor: '#383a42',
14
    lineColor: '#6b6b6b',
15
    secondaryColor: '#f0f0f0',
16
    titleColor: '#383a42',
17
  },
18
} as const;
19

20
function getMermaidConfig(isDark: boolean): MermaidConfig {
21
  const palette = isDark ? mermaidThemePalette.dark : mermaidThemePalette.light;
22
  const background = getComputedStyle(document.documentElement)
23
    .getPropertyValue(isDark ? '--surface-media-stage-dark' : '--surface-media-stage')
24
    .trim();
25

26
  return {
27
    startOnLoad: false,
28
    theme: 'base',
29
    darkMode: isDark,
30
    look: 'handDrawn',
31
    themeVariables: {
32
      background,
33
      primaryColor: palette.primaryColor,
34
      primaryTextColor: palette.primaryTextColor,
35
      lineColor: palette.lineColor,
36
      secondaryColor: palette.secondaryColor,
37
      titleColor: palette.titleColor,
38
      fontFamily: '"Barlow Condensed", sans-serif',
39
    },
40
  };
41
}

Using theme: 'base' with explicit themeVariables gives full control over the colour system. The hardcoded palette values complement the site’s accent pink: primaryColor is a deep rose in dark mode and a pale blush in light mode. fontFamily ties diagram text to the site’s heading typeface, Barlow Condensed.

look: 'handDrawn' enables Mermaid’s hand-drawn rendering style where supported.

A CSS fallback layer covers SVG elements that bypass Mermaid’s themeVariables system, mainly sequence diagram lines and text that have their own rendering path:

1
:global(.mermaid-diagram text),
2
:global(.mermaid-diagram .messageText),
3
:global(.mermaid-diagram .labelText),
4
:global(.mermaid-diagram .loopText),
5
:global(.mermaid-diagram .noteText) {
6
  fill: var(--text-primary) !important;
7
  stroke: none !important;
8
}
9

10
:global(.mermaid-diagram line),
11
:global(.mermaid-diagram path.arrowMarkerPath),
12
:global(.mermaid-diagram .messageLine0),
13
:global(.mermaid-diagram .messageLine1) {
14
  stroke: var(--text-primary) !important;
15
}

var(--text-primary) resolves correctly in both light and dark contexts without any JavaScript.

Re-rendering on theme toggle

Because Mermaid bakes colours into the SVG at render time, toggling between light and dark mode after the page loads leaves diagrams in the wrong theme. The solution is to watch for theme changes and re-render from stored definitions.

The theme toggle in this site sets data-theme directly on <html> via setAttribute; no custom event is dispatched. A MutationObserver watching the data-theme attribute is the only reliable way to detect the change from inside a layout component’s script:

1
new MutationObserver(async (mutations) => {
2
  for (const m of mutations) {
3
    if (m.attributeName === 'data-theme') {
4
      await renderDiagrams();
5
      break;
6
    }
7
  }
8
}).observe(document.documentElement, {
9
  attributes: true,
10
  attributeFilter: ['data-theme'],
11
});

No separate button-reattachment step is needed. renderDiagrams() already re-appends each stored button from the definitions Map after mermaid.run() resolves, so buttons are always present after any render, initial or triggered.

The result: diagrams re-render correctly every time the user toggles the theme.

The expand button and lightbox

Sequence diagrams, especially detailed ones, can be hard to read at the width of a prose column. Each rendered diagram gets an Expand button that opens a near-fullscreen lightbox.

The lightbox is a single DOM element created once and shared between diagram expand and zoomable images. It carries role="dialog", aria-modal="true", and an accessible aria-label, and supports three close mechanisms: the Close button, clicking the dark overlay backdrop, and pressing Escape.

The expand handler clones the SVG, strips the constrained inline dimensions Mermaid sets, and sizes it to fill the available viewport using the SVG’s viewBox:

1
expandBtn.addEventListener('click', () => {
2
  const svgClone = container.querySelector('svg')!.cloneNode(true) as SVGElement;
3
  svgClone.removeAttribute('style');
4
  svgClone.removeAttribute('width');
5
  svgClone.removeAttribute('height');
6
  const viewBoxAttr = svgClone.getAttribute('viewBox');
7
  if (viewBoxAttr) {
8
    const parts = viewBoxAttr.trim().split(/[\s,]+/).map(Number);
9
    if (parts.length === 4 && parts[2] > 0 && parts[3] > 0) {
10
      const rem = parseFloat(getComputedStyle(document.documentElement).fontSize);
11
      const availW = window.innerWidth * 0.98 - 4 * rem;
12
      const availH = window.innerHeight * 0.94 - 4 * rem;
13
      const scale = Math.min(availW / parts[2], availH / parts[3]);
14
      svgClone.style.width = `${Math.round(parts[2] * scale)}px`;
15
      svgClone.style.height = `${Math.round(parts[3] * scale)}px`;
16
    }
17
  } else {
18
    svgClone.style.width = '100%';
19
    svgClone.style.height = 'auto';
20
  }
21
  svgClone.style.display = 'block';
22
  lightboxScroll.appendChild(svgClone);
23
  lightbox.classList.add('is-open');
24
  document.documentElement.style.overflow = 'hidden';
25
  document.body.style.overflow = 'hidden';
26
  closeBtn.focus();
27
});

Reading viewBox gives the intrinsic diagram dimensions. Scaling both axes by Math.min(availW / vbW, availH / vbH) fills as much of the viewport as possible while maintaining aspect ratio. The removeAttribute calls are still necessary: Mermaid also sets inline width and height that would override the computed style values.

On close, the cloned SVG is removed from the DOM and scroll is restored on both <html> and <body>.

Button styling

The expand button uses the shared .media-expand-btn class, which also styles the expand button on zoomable images. The visual pattern matches the code block copy button: dark-ink defaults in light mode, white-tinted values in dark mode, and a pink hover state.

Using separate top-level :global() rules rather than nested &:hover inside :global() is important: Astro’s scoped style processor doesn’t expand nested selectors inside :global(), so the nested form is silently ignored.

1
:global(.media-expand-btn) {
2
  background: rgba(0, 0, 0, 0.06);
3
  border: 1px solid rgba(0, 0, 0, 0.18);
4
  color: rgba(0, 0, 0, 0.55);
5
  /* ... positioning, font, transition ... */
6
}
7

8
:global([data-theme='dark'] .media-expand-btn) {
9
  background: rgba(255, 255, 255, 0.08);
10
  border-color: rgba(255, 255, 255, 0.18);
11
  color: rgba(255, 255, 255, 0.6);
12
}
13

14
:global(.media-expand-btn:hover) {
15
  background: rgba(232, 0, 106, 0.12);
16
  border-color: rgba(232, 0, 106, 0.5);
17
  color: #e8006a;
18
}

Using it in Markdown

Write a fenced code block with the mermaid language identifier. Add a title attribute in the info string to give screen readers a meaningful label:

1
```mermaid title="Sequence diagram: user sends a POST request, API returns 202"
2
sequenceDiagram
3
    actor User
4
    participant API
5
    User->>API: POST /request
6
    API-->>User: 202 Accepted
7
```

That’s all: no shortcodes, no MDX components, no front matter flags. An interactive, themeable diagram with an expand button appears in place of the code block.

The title is optional. Diagrams without one still render correctly and receive role="img" with a generic aria-label="Diagram" as a baseline fallback.

One caveat worth knowing: the look: 'handDrawn' option only applies to diagram types that use Mermaid’s shared node/edge renderer: flowcharts, class diagrams, ER diagrams, and state diagrams. Sequence diagrams have their own rendering path and render in the classic style regardless. The same flow expressed as a flowchart picks up the hand-drawn treatment:

What this doesn’t handle

JavaScript-disabled environments. The CSS-animated skeleton is visible from first paint, but if JavaScript is disabled entirely, the skeleton stays in place and no diagram SVG is ever rendered. If that matters, the rehype plugin approach is the right choice.

OG images and static crawlers. Diagrams don’t appear in generated social preview images or in crawlers that don’t execute JavaScript. Those environments receive the skeleton HTML.

Wrap-up

The full implementation, including the remark plugin, the client script, and the skeleton CSS, lives in the site repository. If you’re adding Mermaid to your own Astro project, the remark plugin and the CDN loading pattern are the two pieces most worth adapting: they sidestep the headless browser dependency and keep the build simple.

Working on something similar?

If you’re building a content site or developer blog and want help with the implementation details, I’m available for consulting. Get in touch via the contact page and tell me what you’re working on.