Astro diagrams

Task: add support for diagrams to Astro.

Ideally:

• 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

Most popular (at the moment) option for diagrams is Mermaid. There are other options though.

Options #

There are several ways to do it:

• (1) Traditional way, which is used by Hugo and other static website generators. Embed mermaid and do rendering on the client side.
  • Because Mermaid doesn’t support server side rendering
  • astro#4433
• (2) Prerender with the help of headless browser (puppeteer, playwright or even Tauri)
  • remark/rehype
    • starlight#1259
    • rehype-mermaid
    • remark-mermaidjs
  • astro-diagram
• (3) Use Mermaid syntax, but render it with Pintora
  • astro-pintora
  • Pintora supports a lot of Mermaid diagrams (which are interesting to me), except Flowchart
    • There is a way to add new diagrams

Dark mode (theme) #

• (1) Congo theme has a good example on how to support dark mode with CSS variables. See congo/mermaid.js
• (2) and (3)
  • prerender diagram in both variants (dark and light) and use picture + <source media="(prefers-color-scheme: dark)">
  • one can put <style type="text/css"> @media (prefers-color-scheme: dark) { ... } inside SVG
  • use CSS variables instead of actual colors in theme, but this is not possible neither in Pintora, neither in Mermaid, because they both manipulate colors (with tinycolor)

Pan/Zoom/Drag #

• (1)
  • Not supported out of the box, needs additional work
• (2) and (3)
  • svg-pan-zoom-gesture

Read more: Text to diagram, BEOE