Mermaid diagrams in Markdown

There are many diagramming languages (see text-to-diagram ↗). Mermaid ↗ seems to be popular, as it is supported by GitHub.

There are two options:

rehype-mermaid - the original plugin. Battle-tested and well supported.
@beoe/rehype-mermaid - my experiment. It is based on mermaid-isomorphic (the same one used by rehype-mermaid). It also adds:
- Selector-based dark mode ↗. Used by Starlight and others.
- Cache to prevent the permanent launch of a headless browser.
- Out-of-the-box compatibility with pan and zoom "plugin".

@beoe/rehype-mermaid

Installation

Install dependencies

pnpm add @beoe/rehype-mermaid
pnpm dlx playwright-core install --with-deps chromium

Configure Astro. See note about Rehype Plugins for Code.

import { rehypeMermaid } from "@beoe/rehype-mermaid";

export default defineConfig({
  integrations: [
    starlight({
      customCss: ["./src/styles/custom.css"],
    }),
  ],
  markdown: {
    rehypePlugins: [
      [
        rehypeMermaid,
        { class: "not-content", strategy: "img-class-dark-mode" },
      ],
    ],
  },
});

Add CSS for dark mode:

html[data-theme="light"] .beoe-dark {
  display: none;
}

html[data-theme="dark"] .beoe-light {
  display: none;
}

Optional install dependency for cache
Terminal window
```
pnpm add @beoe/cache
```

Optional configure cache

import { getCache } from "@beoe/cache";

const cache = await getCache();

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        rehypeMermaid,
        { class: "not-content", strategy: "img-class-dark-mode", cache },
      ],
    ],
  },
});

Optional add pan and zoom for diagrams

rehype-mermaid

Installation

Install dependencies
Terminal window
```
pnpm add rehype-mermaid
```

Configure Astro. See note about Rehype Plugins for Code.

import { rehypeMermaid } from "rehype-mermaid";

export default defineConfig({
  markdown: {
    rehypePlugins: [rehypeMermaid],
  },
});

Strategies

	`inline-svg`	`img-svg`
Supports `css` ↗ option	✔️ Yes	No
Text is searchable (`Cmd` + `F`)	✔️ Yes	No
Supports `dark` ↗ mode (1)	No	✔️ Yes
Issues with `rehype-raw` ↗ (2)	Yes	✔️ No
Other CSS on the page may conflict (3)	Yes	✔️ No

inline-svg is the default strategy.

(1) dark mode

To enable dark mode, use:

export default defineConfig({
  markdown: {
    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
  },
});

However, it doesn’t work with Starlight’s selector-based dark mode. See starlight#1829 ↗.

(2) issues with rehype-raw

I only noticed issues with the sankey diagram, so this is a minor issue.

(3) other CSS

You can style inline SVG with CSS:

svg[id^="mermaid"] {
  /* undo global styles */
  .node .label {
    line-height: 1.2;
  }

  /* primitive dark mode */
  .flowchart-link {
    stroke: var(--sl-color-white) !important;
  }

  .marker {
    stroke: var(--sl-color-white);
    fill: var(--sl-color-white) !important;
  }

  .node-labels {
    fill: var(--sl-color-white);
  }
}

Example

```mermaid
flowchart LR
    Start --> Stop
```