Add Mermaid Diagrams

Note

For the best experience, we recommend using astro-mermaid to render Mermaid diagrams in Astro.

This guide helps you add Mermaid diagrams to your Starlight documentation site using rehype-mermaid.

Step-by-step Guide

1. Install dependencies

   First, install rehype-mermaid and Playwright (required for rendering):

   npm

   npm add rehype-mermaid playwright playwright-chromium

   pnpm

   pnpm add rehype-mermaid playwright playwright-chromium

   Yarn

   yarn add rehype-mermaid playwright playwright-chromium

   Bun

   bun add rehype-mermaid playwright playwright-chromium

2. Configure Astro

   Update your astro.config.mjs:

   astro.config.mjs

   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import rehypeMermaid from "rehype-mermaid";
   
   export default defineConfig({
     markdown: {
       syntaxHighlight: {
         type: "shiki",
         excludeLangs: ["mermaid", "math"],
       },
       rehypePlugins: [rehypeMermaid],
     },
     integrations: [
       starlight({
         customCss: ["./src/styles/mermaid.css"],
       }),
     ],
   });

Example Usage

Create a sample file like src/content/docs/example.mdx and include the following:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

The diagram above will render like this:

Resources

1. astro-mermaid
2. Mermaid Diagrams in Markdown with Astro - Astro Digital Garden