Mermaid diagrams in markdown

Example taken from mermaid.js.org

There are a lot of diagraming languages (see text-to-diagram). Mermaid seems to be popular (it is supported by GitHub).

There are two options:

rehype-mermaid - 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). But it also adds:
- Selector based dark mode. Used by Starlight and others
- cache - to prevent permanent launch of headless browser
- out of the box compatible with pan and zoom "plugin"

@beoe/rehype-mermaid

Installation

Install dependencies
Terminal window
```
pnpm add @beoe/rehype-mermaid
```

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 deafault strategy.

(1) dark mode

In order to enable dark mode use:

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

But it doesn’t work with Starlight’s slector based dark mode. See starlight#1829.

(2) issues with rehype-raw

I noticed issues only with sankey diagram. So this is minor issue

(3) other CSS

You may 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
```