Migration to v3

Version 3 requires Node.js >=22.19.0, Nuxt ^4.1.0, and Nuxt Content >=3.5.0 <4.0.0. Upgrade those dependencies, install the 3.x package, and then apply the configuration changes below.

Rename the module key

contentMermaid is the only supported Nuxt configuration key. Replace the v2 compatibility alias everywhere:

// v2 compatibility alias — removed
export default defineNuxtConfig({
  mermaidContent: { debug: true },
})

// v3
export default defineNuxtConfig({
  contentMermaid: { debug: true },
})

Keep module activation at build time

contentMermaid.enabled decides whether Nuxt installs the Markdown transform and runtime integration. Keep it in Nuxt configuration:

export default defineNuxtConfig({
  contentMermaid: { enabled: false },
})

Do not move enabled into runtimeConfig.public.contentMermaid; changing public runtime data cannot activate or deactivate a module after Nuxt starts.

Transport only pure data at runtime

runtimeConfig.public.contentMermaid accepts data that Nuxt can serialize: strings, booleans, null, finite numbers, plain objects, and arrays. Do not put functions, class instances, symbols, undefined, cycles, or other client-only capabilities there.

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      contentMermaid: {
        loader: { init: { flowchart: { curve: 'basis' } } },
      },
    },
  },
})

Pass a supported client-only value directly to <Mermaid :config="..."> instead.

Choose page or direct Mermaid config

For Content-authored Markdown, put pure-data Mermaid configuration in the page's config frontmatter:

---
config:
  theme: forest
---

```mermaid
flowchart LR
  Page --> Diagram
```

For application code, pass config directly to the Mermaid component. The component's pageConfig and config props are alternatives; providing both is a configuration error.

Account for property-presence merge

In v3, an absent property falls back to the lower configuration layer. A present value replaces it unless both values are plain objects. This means false, 0, '', null, empty arrays, and non-empty arrays are intentional overrides rather than requests for a default.

Review configuration that previously relied on defu-style backfilling, especially empty and falsy values.

Treat expand booleans as resets

expand: true and expand: false reset the complete expand state to the corresponding package preset. An options object patches individual properties.

// A lower layer disabled expansion.
{ expand: false }

// This changes the margin but does not re-enable expansion.
{ expand: { margin: 32 } }

// Re-enable it explicitly.
{ expand: { enabled: true, margin: 32 } }

Remove useColorModeTheme

theme.useColorModeTheme is accepted in v3 only as a no-op for compatibility. It does not enable or disable color-mode integration, so remove the key. Configure theme.light and theme.dark; when @nuxtjs/color-mode is installed, integration is automatic.

Remove package-root transform imports

Version 3 removes the undocumented package-root export transformMermaidCodeBlocks. There is no replacement public transform API. Register the Nuxt module and let it own Markdown transformation.

Migration checklist

• Upgrade Node.js, Nuxt, and Nuxt Content to the supported ranges.
• Install the 3.x package.
• Replace mermaidContent with contentMermaid.
• Keep enabled in build-time module configuration.
• Keep public runtime configuration serializable and pure-data only.
• Use page configuration for Markdown or direct config for Vue, never both on one component.
• Review empty and falsy overrides under property-presence merge.
• Review expand boolean resets and re-enable expansion explicitly when needed.
• Remove theme.useColorModeTheme.
• Remove imports of transformMermaidCodeBlocks.
• Run a production build and reload a migrated Content route.