Non-standard diagrams
This package does not parse arbitrary diagram DSLs. Both Mermaid.js and Excalidraw still start from Mermaid-compatible input
That boundary is strict, but the escape routes are practical
Rewrite the source as Mermaid
Many custom-looking diagrams are still just boxes, labels, and links underneath
That route keeps authoring in Markdown and keeps the full runtime shell
Switch the renderer to Excalidraw
renderEngine: 'excalidraw' changes the output style, not the parser
This is the right choice when the source is Mermaid but the visual target is rougher and more hand-drawn
Preprocess a custom DSL into Mermaid
Some teams already have domain-specific syntax. In that case, the cleanest move is a thin preprocessing plugin placed before markdown-it-mermaid-enhanced
import { defineConfig } from 'vitepress'
import markdownItMermaidEnhanced from 'markdown-it-mermaid-enhanced'
function customDiagramPlugin(md: any) {
md.core.ruler.before('normalize', 'custom-diagram-rewrite', (state) => {
// detect custom syntax and rewrite it into Mermaid fences
})
}
export default defineConfig({
markdown: {
config: (md) => {
md.use(customDiagramPlugin)
md.use(markdownItMermaidEnhanced)
},
},
})That keeps one runtime, one toolbar, and one export path
Fall back to SVG or PNG assets
When layout rules sit outside Mermaid entirely, static assets are still the honest answer
A practical decision rule
- Mermaid-compatible structure: rewrite into Mermaid and stay in the package flow
- Mermaid-compatible structure with a sketchier target: keep the Mermaid source, switch to Excalidraw
- Repeated bespoke syntax with stable semantics: add a preprocessing step
- Pixel-perfect artwork or unsupported layout rules: embed static assets