Mermaid support with theme switching for VitePress 2

[nicolas-goudry]

I wanted to share the solution I came up with for adding Mermaid diagram support to VitePress 2 with proper dark/light theme switching.

The Journey

I initially tried the vitepress-plugin-mermaid plugin, but it's not compatible with VitePress 2 and hasn't been updated in over 3 years.

I also looked at the markdown-it-mermaid plugin, but I got an error when registering it with VitePress and it hasn't been updated in over 8 years.

So I decided to build something from the ground up, in two pieces:

• A custom markdown-it plugin: responsible for looking at fenced code blocks and convert mermaid ones to the Vue component
• A Vue component: responsible for rendering the diagrams using Mermaid.js

The Vue component also features some VitePress-related niceties:

• Automatic switch between light/dark themes
• Prevents content shifting during theme changes (since diagrams are re-rendered)
• Avoids flashing diagram source text during theme changes and on initial render

I started with the vue-mermaid-string package, which worked well for basic functionality. However, I ran into issues:

1. ID collisions: when multiple diagrams rendered simultaneously, nanoid() (which uses timestamps) occasionally generated duplicate IDs, causing diagrams to render in the wrong containers
2. Theme switching: the component didn't reactively update when VitePress theme changed
3. Visual glitches: content would shift and flash during theme transitions

Hence, I decided to inspire myself from this component and implement a minimal solution using the Mermaid library directly.

Implementation

Directory structure

.vitepress
├── plugins
│   └── vitepress-mermaid
│       ├── index.ts
│       └── index.vue
├── theme
│   └── index.ts
└── config.mts

Markdown-it Plugin

This is the simplest piece of code. I was mainly inspired by the snippet plugin from VitePress.

.vitepress/plugins/vitepress-mermaid/index.ts

import type MarkdownIt from 'markdown-it'

export const mermaidPlugin = (md: MarkdownIt) => {
  const fence = md.renderer.rules.fence!

  // Override the fence renderer
  md.renderer.rules.fence = (...args) => {
    const [tokens, idx] = args
    const token = tokens[idx]
    const lang = token.info.trim()

    // Check if this is a mermaid code block
    if (lang === 'mermaid') {
      const code = token.content.trim()

      return `<vitepress-mermaid value="${md.utils.escapeHtml(code)}"></vitepress-mermaid>\n`
    }

    // For non-mermaid code blocks, use the default renderer
    return fence(...args)
  }
}

Vue Component

This is the heart of the integration. I was mainly inspired by vue-mermaid-string, and got some help from Claude Sonnet 4.5.

Some key features are:

• :key="theme": forces Vue to recreate the component when theme changes, ensuring mermaid re-renders with the correct theme
• fixedHeight: captures the diagram height after first render to prevent content shifting during theme transitions
• .mermaid:has(> svg): CSS-only solution to hide the diagram source text until next diagram is fully rendered, preventing flash

.vitepress/plugins/vitepress-mermaid/index.vue

<template>
  <div :key="theme" ref="diagramRef" class="mermaid" :style="{ minHeight: fixedHeight }">
    {{ value }}
  </div>
</template>

<script setup>
import { useData } from 'vitepress'
import { computed, ref, watch, nextTick } from 'vue'
import mermaid from 'mermaid'

const props = defineProps({
  value: String
})

const { isDark } = useData()
const theme = computed(() => isDark.value ? 'dark' : 'default')

const diagramRef = ref(null)
const fixedHeight = ref('auto')

// Initialize mermaid
mermaid.initialize({
  startOnLoad: false,
  theme: theme.value,
})

watch(diagramRef, async () => {
  const element = diagramRef.value
  if (!element) return

  await nextTick()

  // Update mermaid config with current theme
  mermaid.initialize({
    startOnLoad: false,
    theme: theme.value,
  })

  // Remove any previous processing
  element.removeAttribute('data-processed')

  // Render the diagram
  try {
    await mermaid.run({
      nodes: [element]
    })

    // Capture height after render
    setTimeout(() => {
      if (element) {
        const height = element.offsetHeight
        if (height > 0) {
          fixedHeight.value = `${height}px`
        }
      }
    }, 100)
  } catch (error) {
    console.error('Mermaid rendering error:', error)
  }
}, { immediate: true })
</script>

<style scoped>
.mermaid {
  display: flex;
  justify-content: center;
  margin: 1rem 0;
  opacity: 0;
  transition: opacity 300ms ease;
}

.mermaid:has(> svg) {
  opacity: 1;
}
</style>

VitePress Config

.vitepress/config.mts

import { defineConfig } from 'vitepress'
import { mermaidPlugin } from './plugins/vitepress-mermaid'

export default defineConfig({
  // ... VitePress config

  markdown: {
    config: (md) => {
      md.use(mermaidPlugin)
    }
  }
})

Theme Registration

.vitepress/theme/index.ts

import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import VitePressMermaid from '../plugins/vitepress-mermaid/index.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('vitepress-mermaid', VitePressMermaid)
  },
} satisfies Theme

Result

Now I can use mermaid diagrams in markdown:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

And they'll automatically switch themes with VitePress theme switching.

Overall, this was a fun exercise in building a minimal, focused solution. Sometimes it's better to use a library directly rather than wrapping it, especially when you need specific behavior like reactive theme switching.

Hope this helps others looking to add Mermaid support to VitePress!