the problem
VitePress renders Mermaid code blocks as static SVGs. Complex diagrams — architecture maps, sequence flows, ER schemas — become unreadable at default scale. Existing plugins either don’t support interaction or break on dark mode and touch devices.
the approach
A VitePress plugin that intercepts ```mermaid fences and renders them as interactive
<Mermaid> components. Click any diagram to open a fullscreen viewer with zoom (buttons,
mouse wheel, pinch-to-zoom), pan/drag, keyboard navigation, and SVG/PNG download.
Dark/light theme reactivity out of the box. Per-page theme override via mermaidTheme
frontmatter. Fully keyboard accessible — Enter/Space to open, +/-/0/arrows inside the
viewer, ARIA labels and focus management.
Setup is one line with the withMermaid() wrapper, or manual via MermaidPlugin +
MermaidMarkdown for fine-grained control.
stack
- TypeScript, Vue 3
- VitePress plugin architecture (Vite plugin + markdown-it plugin)
- Mermaid.js for diagram rendering
links
- Docs & demo: https://kassaila.github.io/vitepress-mermaid-viewer/
- npm:
vitepress-mermaid-viewer - Repo: https://github.com/Kassaila/vitepress-mermaid-viewer