Skip to content
Astro Digital Garden

Diagrams support in Markdown

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

Ideal solution

  • it would be rendered as SVG on the server side
    • so no JS required on the client-side
    • people can use Cmd + F to search text
  • style it with CSS-variables (or CSS-classes)
    • so it would be possible to implement dark mode without JS
  • optionally add small JS to implement pan/zoom/drag

Options

There is no ideal solution so far. But here is what we can do instead:

  • Client-side rendering with Mermaid
  • Server-side rendering with Mermaid via headless browser
  • Server-side rendering with Pintora ↗

See: astro-diagrams ↗

Server-side rendering via headless browser

remark plugin

Instal dependencies…
pnpm add remark-mermaidjs
astro.config.mjs
import remarkMermaidjs from "remark-mermaidjs";


export default defineConfig({
  integrations: [
    starlight({
      customCss: ["./src/styles/custom.css"],
    }),
  ],
  markdown: {
    remarkPlugins: [remarkMermaidjs],
  },
});

Author advices against using remark plugin and insists on using rehype plugin ↗.

You may need to fix some CSS for your diagrams, for example:

src/styles/custom.css
svg .node .label {
  line-height: 1.2;
}


.flowchart-link {
  stroke: var(--sl-color-white) !important;
}


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

rehype plugin

rehype-mermaidjs doesn’t work with Astro out of the box. Because of remark-shiki ↗. There are several workarounds:

There is upcoming feature to support dark mode: rehype-mermaid#6 ↗.

Example

example.md
```mermaid
flowchart LR
    Start --> Stop
```

Start
Stop

Further improvements