How to Integrate Mermaid Diagrams in Astro Projects

Astro is a modern static site builder that supports Markdown and MDX for content. With Astro 5.5+, you can easily render Mermaid diagrams in your markdown using the official rehype-mermaid plugin. This guide walks you through the setup, usage, and troubleshooting.

Why Mermaid?

Mermaid lets you create flowcharts, sequence diagrams, and more using a simple text syntax. It’s perfect for technical blogs, documentation, and visualizing workflows.

Content Flow Overview

Here’s how the integration works:

Step 1: Install Dependencies

npm install rehype-mermaid

If you use Mermaid diagrams, rehype-mermaid requires Playwright and its browser dependencies:

npm install playwright
npx playwright install

On Linux, you may need extra system packages (see Playwright docs).

Step 2: Update `astro.config.mjs`

Add rehype-mermaid to your markdown config and exclude Mermaid from syntax highlighting:

import { defineConfig } from 'astro/config';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid'],
    },
    rehypePlugins: [rehypeMermaid],
  },
});

Step 3: Write Markdown with Mermaid Diagrams

You can now use mermaid code blocks in your markdown files:

Step 4: Build and Preview

npm run dev

Visit your site and you should see SVG diagrams rendered from your mermaid blocks.

Troubleshooting

Blank page or build error?
- Check for syntax errors in your mermaid diagrams.
- Make sure Playwright and its browsers are installed.
- On Linux, install required system packages (see Playwright warnings).
Only some pages fail?
- Comment out mermaid blocks and add them back one by one to find the problematic diagram.
Diagram not rendering, but code block shows?
- Ensure excludeLangs: ['mermaid'] is set in your config.

Example: Sequence Diagram

References

With this setup, you can create beautiful, interactive diagrams in your Astro site using just Markdown and a few lines of config!