Official Mermaid support

[jd-solanki]

Is your feature request related to a problem? Please describe.

This days having mermaid support in markdown based content framework is common. Current DIY solutions end up issues with VitePress due to its alpha version.

Describe the solution you'd like

official built-in mermaid support

Describe alternatives you've considered

None

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[cschanhniem]

This is a well-scoped feature request. A few concrete observations from implementing Mermaid in similar SSG pipelines that may help anyone picking this up:

Compilation pipeline fit: VitePress processes Markdown through markdown-it, so the cleanest fit is a markdown-it plugin (like markdown-it-mermaid-style) that transforms ```mermaid fenced blocks into <div class="mermaid"> containers at parse time, before Vue compilation. This avoids fighting with VitePress's HTML-in-Markdown handling (which is relevant to #5220's issue too — raw HTML and Markdown coexist by routing through different parser paths).

Incremental build gotcha: Mermaid renders to SVG via a client-side library (mermaid.js, ~1MB). If you server-side render at build time, the SVG output is static and caches cleanly. If you client-side render, every page navigation re-executes the Mermaid parser, which is a meaningful perf hit on docs with 20+ diagrams — and it interacts poorly with VitePress's pre-fetching. The Docusaurus and Nextra implementations both settled on build-time rendering for this reason.

Bundle strategy: Shipping mermaid in the theme bundle adds ~800KB gzipped. A lazy-load approach (dynamic import only when a .mermaid class is detected in the DOM) keeps the default bundle small. VitePress can gate this behind a themeConfig.mermaid: true flag so users opt in.

Happy to help review a PR if someone takes this on — the markdown-it plugin path is probably a 50-line addition to src/node/markdown/markdown.ts.