Add Mermaid Diagrams

Caution

This recipe requires Astro v7, Starlight v0.41, Sätteri and @astrojs/markdown-satteri.

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 Sätteri.

Step-by-step Guide

1. Install dependencies

   Install satteri and @astrojs/markdown-satteri:

   npm

   npm add satteri @astrojs/markdown-satteri

   pnpm

   pnpm add satteri @astrojs/markdown-satteri

   Yarn

   yarn add satteri @astrojs/markdown-satteri

   Bun

   bun add satteri @astrojs/markdown-satteri

2. Create the Sätteri Mermaid plugin

   Save the following code as src/plugins/satteri-mermaid.ts:

   src/plugins/satteri-mermaid.ts

   import { defineHastPlugin } from "satteri";
   
   export const satteriMermaid = defineHastPlugin({
     name: "mermaid",
     element: {
       filter: ["pre"],
       visit(node, ctx) {
         const codeChild = node.children?.find(
           (c) => c.type === "element" && (c as any).tagName === "code",
         );
         if (!codeChild || codeChild.type !== "element") return;
   
         const lang = (codeChild as any).data?.lang;
   
         if (lang === "mermaid") {
           const text = ctx.textContent(codeChild);
           ctx.replaceNode(node, {
             type: "element",
             tagName: "div",
             properties: { className: ["mermaid"] },
             children: [{ type: "text", value: text }],
           } as any);
         }
       },
     },
   });

3. Configure Astro

   Update your astro.config.mjs to use the Sätteri processor with the satteriMermaid plugin:

   astro.config.mjs

   import { satteri } from "@astrojs/markdown-satteri";
   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import { satteriMermaid } from "./src/plugins/satteri-mermaid";
   
   export default defineConfig({
     markdown: {
       syntaxHighlight: {
         type: "shiki",
         excludeLangs: ["mermaid"],
       },
       processor: satteri({
         hastPlugins: [satteriMermaid],
       }),
     },
     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. Sätteri
2. Mermaid Diagrams in Markdown with Astro - Astro Digital Garden