On this page
13. Mermaid Pipeline (Phase 1–3)
The Mermaid integration was developed in three phases, each with its own optimization.
Phase 1: Client Render (Live Preview)#
In the preview iframe, Mermaid is dynamically imported (~400 KB gzip) only if the page actually has a mermaid fence. Module-level Singleton — one init per iframe.
Phase 2: Server-Side Render (Static Export)#
In the deploy path, the HTML must work without JS. Solution: JSDOM loads in the API process, mermaid renders there against the fake DOM, the resulting SVG is written inline into the HTML file. Concurrency: a module-level Mutex serializes the renders (mermaid shares the DOM).
Phase 3: Pack-aware Theming#
mermaidThemeForPack(slug) in packages/render-engine/src/packs/mermaid-themes.ts translates pack tokens (HSL) → Mermaid themeVariables (hex). Both server and client do this. Result: Diagrams in obsidian-luxury have gold accents, in retro-future magenta — all automatically.
Phase 3.5: Lightbox#
Every rendered diagram has a Maximize icon in the top right (hover-revealed). Click → native `` with backdrop-filter: blur(6px), ESC closes. Works equally well in Static Export and Live Preview — Static via delegated data-mermaid-expand-Click-Handler in inline JS, Live via React refs.