Migrating from v2

Every breaking change when upgrading @movk/nuxt-docs from v2 to v3, each with a v2 and v3 comparison. Work through dependencies and feature flags, content paths, config fields, visual defaults and component overrides in order to finish the upgrade.
Requires
@movk/nuxt-docs 3.0
Difficulty
Intermediate
View source

Upgrade steps

  1. Upgrade @movk/nuxt-docs to ^3.0.0
  2. Install the optional dependencies you use, see Dependencies and feature flags
  3. Make sure your docs live in content/docs/
  4. Review app.config.ts and any overridden components
  5. Run nuxt build. Missing dependencies and conflicting options fail the build with an explanation

Migrate with AI

Give the prompt below to a coding agent such as Claude Code, Cursor or Codex. It checks and updates your project against the changes on this page. Agents can also read the Markdown version of this page directly: https://docs.mhaibaraai.cn/raw/en/docs/getting-started/migration.md.

Dependencies and feature flags

v3 turns the dependencies of features that are off by default into optional peers, cutting the layer's direct dependencies from 47 to 35. If you enable a feature without its dependencies, the build fails and prints the install command. See Feature Flags for details.

Component docs are off by default

ComponentProps, ComponentSlots, ComponentEmits, ComponentCode and ComponentExample must be enabled explicitly:

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  movkNuxtDocs: {
    componentDocs: true
  }
})

Install dependencies for AI Chat, accessibility checks and i18n

AI Chat turns on under the same conditions as before: AI_API_KEY is present at build time, or aiChat.enabled: true is set. The difference is that its dependencies no longer ship with the layer:

# AI Chat
pnpm add ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
# movkNuxtDocs.a11y: true
pnpm add @nuxt/a11y
# @nuxtjs/i18n in modules
pnpm add @nuxtjs/i18n

@nuxt/a11y is off by default in v3; set movkNuxtDocs.a11y: true to enable it.

Mermaid fails the build when dependencies are missing

In v2, enabling Mermaid without mermaid / dompurify installed was silently skipped. v3 fails the build instead:

pnpm add mermaid dompurify

MCP cannot be disabled while AI Chat is on

AI Chat retrieves docs through the MCP Server. Setting both of these throws at build time:

nuxt.config.ts
export default defineNuxtConfig({
  aiChat: { enabled: true },
  movkNuxtDocs: {
    mcp: false // Error: aiChat depends on the MCP Server
  }
})

Content directory

Docs must live in content/docs/, other locales in content/{locale}/docs/, and the route prefix is always /docs. Without content/docs/, v2 mounted docs at the root path, but docs pages were unreachable in that mode, so v3 removes it.

# v2: directly under content/
content/
├── 1.getting-started/
└── 2.guide/

# v3: move into content/docs/
content/
└── docs/
    ├── 1.getting-started/
    └── 2.guide/

The build log prints a warning when content/docs/ is missing.

Config fields

github.per_page is renamed to github.perPage

app/app.config.ts
export default defineAppConfig({
  github: {
-   per_page: 50
+   perPage: 50
  }
})

Commits are no longer filtered by date

v2 defaulted since to 2025-01-31 and until to the build time, hiding commits older than that date or made after the build. In v3, github.since and github.until are empty by default, with no limit. Set them explicitly to restrict the range:

app/app.config.ts
export default defineAppConfig({
  github: {
    since: '2025-01-01T00:00:00Z'
  }
})

Author-specific defaults are removed

The v3 package no longer ships these defaults. Set them in your own config if you need them:

v2 defaultv3 defaultHow to restore
header.avatar pointing to the author's avatar''Set header.avatar
github.dateFormat.options.timeZone: 'Asia/Shanghai'No time zoneSet timeZone in github.dateFormat.options
Loads the Alibaba PuHuiTi font CDNNot loadedSee Fonts below

Header navigation and sidebar categories

In v2 you defined navigation by overriding useHeader / useCategory in app/composables/. v3 recommends declaring it in app.config.ts: labels can be localized, and internal links get the locale prefix and active state automatically. The old way still works.

export function useHeader() {
  const desktopLinks = computed(() => [
    { label: 'Docs', to: '/docs/getting-started', active: useRoute().path.startsWith('/docs') }
  ])
  return { desktopLinks, mobileLinks: desktopLinks }
}

See Navigation and Categories for the fields.

Visual defaults

v3 uses editorial typography as the default look. To keep the v2 appearance, revert the items one by one.

Primary and neutral colors

The default primary color changes from green to vermilion, the neutral from slate to paper, and the background is no longer pure white:

app/app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'green',
      neutral: 'slate'
    }
  }
})

Fonts

The layer loads Inter, Fraunces and JetBrains Mono (Latin only) by default, with serif headings. To use sans-serif everywhere:

app/app.config.ts
export default defineAppConfig({
  theme: {
    font: 'sans'
  }
})

The Alibaba PuHuiTi Chinese font CDN that v2 loaded automatically is gone. The font stack still prefers Alibaba PuHuiTi, so loading the stylesheet yourself is enough:

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      link: [
        { rel: 'stylesheet', href: 'https://your-cdn.example.com/fonts/alibaba-puhuiti.css' }
      ]
    }
  }
})

See Theme and Fonts for adding Chinese serif headings.

Code highlighting theme

Code blocks now use github-light / github-dark instead of the Nuxt Content default theme. Override it in nuxt.config.ts for a different theme:

nuxt.config.ts
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          theme: { default: 'material-theme-lighter', dark: 'material-theme-palenight' }
        }
      }
    }
  }
})

Component overrides

The override contract is the source of truth

From v3, overridable components, where they mount and their props are listed in the override contract table on the Customization page, and stay stable within v3.x. Components that are not listed, such as ThemePickerButton, are internal and may change between versions.

Page structure is redesigned

The header, sidebar, table of contents, previous / next links and footer have new structure and styles. If you overrode these components or depend on their DOM structure in CSS, compare against the new implementation:

  • The header is a two-row masthead: wordmark, text navigation and search on top, the numbered section bar below
  • PageHeaderLinks moves from the right of the page title to the meta row below the lead paragraph
  • The active sidebar item is marked by a vermilion bar on the left

The layer overrides ProsePre

The layer overrides Nuxt UI's ProsePre so the copy button shows "Copy / Copied" text. If you override ProsePre in your project, yours takes precedence.

HeroBackground is removed

The HeroBackground component and the heroBackground page meta are gone. Remove any references:

app/pages/index.vue
<script setup lang="ts">
- definePageMeta({ heroBackground: 'opacity-30' })
</script>

<template>
- <HeroBackground />
  <ContentRenderer :value="page" />
</template>

useToolCall accepts a string state

When overriding useToolCall, the state parameter is widened from the AI SDK's ToolState to string, so core code does not depend on the optional ai package:

app/composables/useToolCall.ts
-export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
+export function useToolCall(state: string, toolName: string, input: Record<string, string | undefined>) {
Copyright © 2024 - 2026