feat: add Mermaid renderer plugin (#2465)

ysknsid25 · web-flow · commit 29b3ed0b1efd · 2026-03-03T10:11:13.000+09:00
diff --git a/docs/.vitepress/customizations.ts b/docs/.vitepress/customizations.ts
@@ -43,6 +43,10 @@ export default [
     text: 'Configure Mermaid',
     link: '/custom/config-mermaid',
   },
+  {
+    text: 'Configure Mermaid Renderer',
+    link: '/custom/config-mermaid-renderer',
+  },
   {
     text: 'Configure Routes',
     link: '/custom/config-routes',
diff --git a/docs/custom/config-mermaid-renderer.md b/docs/custom/config-mermaid-renderer.md
@@ -0,0 +1,19 @@
+# Configure Mermaid Renderer
+
+<Environment type="client" />
+
+1. The user installs the Mermaid library they want to use. e.g.) `npm install beautiful-mermaid`
+2. Create `./setup/mermaid-renderer.ts` with the following content:
+
+```ts
+// setup/mermaid-renderer.ts
+import { defineMermaidRendererSetup } from '@slidev/types'
+// example. https://github.com/lukilabs/beautiful-mermaid?tab=readme-ov-file#readme
+import { renderMermaid } from 'beautiful-mermaid'
+
+export default defineMermaidRendererSetup(() => {
+  return (code, _options) => renderMermaid(code)
+})
+```
+
+This setting allows you to use the 3rd party Mermaid library. Replace the `renderMermaid()` part with the render function of the library.
diff --git a/packages/client/modules/mermaid.ts b/packages/client/modules/mermaid.ts
@@ -1,3 +1,4 @@
+import mermaidRenderers from '#slidev/setups/mermaid-renderer'
 import { clearUndefined } from '@antfu/utils'
 import lz from 'lz-string'
 import mermaid from 'mermaid/dist/mermaid.esm.mjs'
@@ -17,12 +18,24 @@ export async function renderMermaid(lzEncoded: string, options: any) {
   if (_cache)
     return _cache
 
+  const code = lz.decompressFromBase64(lzEncoded)
+
+  // custom renderer
+  for (const setup of mermaidRenderers) {
+    const renderer = await setup()
+    if (renderer) {
+      const svg = await renderer(code, options)
+      cache.set(key, svg)
+      return svg
+    }
+  }
+
+  // fallback: existing mermaid
   mermaid.initialize({
     startOnLoad: false,
     ...clearUndefined(await setupMermaid() || {}),
     ...clearUndefined(options),
   })
-  const code = lz.decompressFromBase64(lzEncoded)
   const id = makeId()
   const { svg } = await mermaid.render(id, code, containerElement)
   cache.set(key, svg)
diff --git a/packages/slidev/node/virtual/setups.ts b/packages/slidev/node/virtual/setups.ts
@@ -16,6 +16,6 @@ function createSetupTemplate(name: string): VirtualModuleTemplate {
 }
 
 // setups
-const setupModules = ['shiki', 'code-runners', 'monaco', 'mermaid', 'main', 'root', 'routes', 'shortcuts', 'context-menu']
+const setupModules = ['shiki', 'code-runners', 'monaco', 'mermaid', 'mermaid-renderer', 'main', 'root', 'routes', 'shortcuts', 'context-menu']
 
 export const templateSetups = setupModules.map(createSetupTemplate)
diff --git a/packages/types/client.d.ts b/packages/types/client.d.ts
@@ -68,6 +68,13 @@ declare module '#slidev/setups/mermaid' {
   export default setups
 }
 
+declare module '#slidev/setups/mermaid-renderer' {
+  import type { MermaidRendererSetup } from '@slidev/types'
+
+  const setups: MermaidRendererSetup[]
+  export default setups
+}
+
 declare module '#slidev/setups/main' {
   import type { AppSetup } from '@slidev/types'
 
diff --git a/packages/types/src/setups.ts b/packages/types/src/setups.ts
@@ -88,6 +88,8 @@ export type AppSetup = (context: AppContext) => Awaitable<void>
 export type RootSetup = () => Awaitable<void>
 export type RoutesSetup = (routes: RouteRecordRaw[]) => RouteRecordRaw[]
 export type MermaidSetup = () => Awaitable<Partial<MermaidConfig> | void>
+export type MermaidRenderFn = (code: string, options: Record<string, any>) => Awaitable<string>
+export type MermaidRendererSetup = () => Awaitable<MermaidRenderFn | void>
 export type ShortcutsSetup = (nav: NavOperations, defaultShortcuts: ShortcutOptions[]) => Array<ShortcutOptions>
 export type CodeRunnersSetup = (runners: CodeRunnerProviders) => Awaitable<CodeRunnerProviders | void>
 export type ContextMenuSetup = (items: ComputedRef<ContextMenuItem[]>) => ComputedRef<ContextMenuItem[]>
@@ -103,6 +105,7 @@ export const defineAppSetup = defineSetup<AppSetup>
 export const defineRootSetup = defineSetup<RootSetup>
 export const defineRoutesSetup = defineSetup<RoutesSetup>
 export const defineMermaidSetup = defineSetup<MermaidSetup>
+export const defineMermaidRendererSetup = defineSetup<MermaidRendererSetup>
 export const defineKatexSetup = defineSetup<KatexSetup>
 export const defineShortcutsSetup = defineSetup<ShortcutsSetup>
 export const defineTransformersSetup = defineSetup<TransformersSetup>
diff --git a/test/mermaid-renderer.test.ts b/test/mermaid-renderer.test.ts
@@ -0,0 +1,31 @@
+import type { ResolvedSlidevOptions } from '@slidev/types'
+import type { PluginContext } from 'rollup'
+import { describe, expect, it } from 'vitest'
+import { templateSetups } from '../packages/slidev/node/virtual/setups'
+
+describe('mermaid-renderer virtual module', () => {
+  it('registers /@slidev/setups/mermaid-renderer', () => {
+    const ids = templateSetups.map(t => t.id)
+    expect(ids).toContain('/@slidev/setups/mermaid-renderer')
+  })
+
+  it('generates content with mermaid-renderer glob', () => {
+    const template = templateSetups.find(t => t.id === '/@slidev/setups/mermaid-renderer')!
+    const content = template.getContent.call({} as PluginContext, {
+      userRoot: '/user/project',
+      roots: ['/user/project'],
+    } as ResolvedSlidevOptions)
+
+    expect(content).toContain('mermaid-renderer')
+    expect(content).toContain('export default')
+    expect(content).toContain('filter(Boolean)')
+  })
+
+  it('comes after mermaid in templateSetups', () => {
+    const ids = templateSetups.map(t => t.id)
+    const mermaidIdx = ids.indexOf('/@slidev/setups/mermaid')
+    const rendererIdx = ids.indexOf('/@slidev/setups/mermaid-renderer')
+    expect(mermaidIdx).toBeGreaterThanOrEqual(0)
+    expect(rendererIdx).toBeGreaterThan(mermaidIdx)
+  })
+})

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,6 @@ function createSetupTemplate(name: string): VirtualModuleTemplate {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`// setups`
`19`		`-const setupModules = ['shiki', 'code-runners', 'monaco', 'mermaid', 'main', 'root', 'routes', 'shortcuts', 'context-menu']`
	`19`	`+const setupModules = ['shiki', 'code-runners', 'monaco', 'mermaid', 'mermaid-renderer', 'main', 'root', 'routes', 'shortcuts', 'context-menu']`
`20`	`20`
`21`	`21`	`export const templateSetups = setupModules.map(createSetupTemplate)`