Adding Mermaid Diagram Support to a Next.js Blog

This article is mostly written by Claude Code

Background

Diagrams are essential for explaining architectures and flows in a technical blog. Rather than opening an image editor every time, I wanted to write diagrams as text directly inside Markdown.

Tech Stack

The content pipeline for this blog looks like this:

Why rehype-mermaid?

There are two main approaches to rendering Mermaid diagrams:

Approach	Pros	Cons
Client-side rendering (mermaid.js)	No Playwright required	~800 KB increase in JS bundle
Build-time rendering (rehype-mermaid)	No client-side JS, SVG inlined directly	Requires Playwright + Chromium

Since this blog already uses a rehype plugin chain, rehype-mermaid is a natural fit.

Installation

yarn add rehype-mermaid playwright
npx playwright install chromium

rehype-mermaid uses mermaid-isomorphic under the hood, which runs mermaid.js inside a headless browser to produce SVG output. This is necessary because mermaid.js itself depends on browser DOM APIs.

The Key: Conditional Loading

The challenge lies in CI environments. Installing Playwright Chromium on every build — even when no post contains a Mermaid diagram — wastes build time unnecessarily.

Solution: Scan the post files at build time and load the plugin only when a ```mermaid block is actually found.

Core Code in contentlayer.config.ts

import { readFileSync, readdirSync } from 'fs'

function hasMermaidBlocks(): boolean {
  const postsDir = path.join(root, 'data', 'posts')
  try {
    return readdirSync(postsDir).some((file) => {
      if (!file.endsWith('.mdx')) return false
      return readFileSync(path.join(postsDir, file), 'utf-8').includes('```mermaid')
    })
  } catch {
    return false
  }
}

// Lazy-load: contentlayer's esbuild targets es2020,
// which doesn't support top-level await, so we wrap it in a function
function lazyRehypeMermaid() {
  let plugin: any = null
  return () => {
    return async (tree: any, file: any) => {
      if (!plugin) {
        const mod = await import('rehype-mermaid')
        plugin = mod.default({ strategy: 'inline-svg' })
      }
      return plugin(tree, file)
    }
  }
}

const useMermaid = hasMermaidBlocks()

// Conditionally append to the rehypePlugins array
rehypePlugins: [
  // ... existing plugins
  ...(useMermaid ? [lazyRehypeMermaid()] : []),
  [rehypePrismPlus, { defaultLanguage: 'js', ignoreMissing: true }],
]

GitHub Actions CI

- name: Check for mermaid diagrams
  id: check-mermaid
  run: |
    if grep -r '```mermaid' data/posts/ >/dev/null 2>&1; then
      echo "found=true" >> $GITHUB_OUTPUT
    else
      echo "found=false" >> $GITHUB_OUTPUT
    fi
- name: Get Playwright version
  if: steps.check-mermaid.outputs.found == 'true'
  id: playwright-version
  run: echo "version=$(npx playwright --version | awk '{print $2}')" >> $GITHUB_OUTPUT
- name: Cache Playwright browsers
  if: steps.check-mermaid.outputs.found == 'true'
  uses: actions/cache@v4
  id: playwright-cache
  with:
    path: ~/.cache/ms-playwright
    key: ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}
- name: Install Playwright Chromium (for mermaid rendering)
  if: steps.check-mermaid.outputs.found == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
  run: npx playwright install --with-deps chromium
- name: Install Playwright deps only (cached browsers)
  if: steps.check-mermaid.outputs.found == 'true' && steps.playwright-cache.outputs.cache-hit == 'true'
  run: npx playwright install-deps chromium

Results

Scenario	CI Behavior
No mermaid blocks	Playwright skipped — no change in build time
mermaid blocks present (cache miss)	Full Playwright + Chromium install (+30–40 seconds)
mermaid blocks present (cache hit)	Browser binary (112 MB) served from cache, only OS deps installed (~5s)

With this setup, simply writing a ```mermaid code block in any post is enough — SVG diagrams are generated automatically at build time.