---
title: "Migrating from v2"
description: "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."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/getting-started/migration"
---
# 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.

## Upgrade steps

1. Upgrade `@movk/nuxt-docs` to `^3.0.0`
2. Install the optional dependencies you use, see [Dependencies and feature flags](#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`.

````md
You are upgrading **this project** (a consumer of @movk/nuxt-docs) to **@movk/nuxt-docs 3.0**.

v3 turns features that are off by default into optional peer dependencies, fixes the content directory, renames some config fields, and makes an editorial layout the new visual default. Most changes fail the build outright; a few (visual defaults, component overrides) only change how the site looks.

Your job:

1. Find code, config and content affected by the changes below, in **this repository only**.
2. Rewrite them to the v3 form. Do not add compatibility shims for the old form.
3. Keep the site's current behavior and look. For the visual defaults in section 6, ask me whether to keep the v2 look before changing anything.
4. When done, run the project's `nuxt build`, typecheck and tests, and fix failures caused by the migration.
5. Finish with a list of changed files, newly installed dependencies, and items I need to review by hand.

## Do not change

- `extends: ['@movk/nuxt-docs']` stays as is
- Overriding `useHeader` / `useCategory` still works; switch to `header.nav` / `docs.categories` in `app.config` only if I agree
- MDC syntax, frontmatter fields and numeric filename prefixes are unchanged
- The `AI_API_KEY`, `AI_BASE_URL` and `NUXT_GITHUB_TOKEN` environment variable names are unchanged

## Prerequisite

Upgrade `@movk/nuxt-docs` to `^3.0.0` first, using the project's package manager:

```bash
pnpm add @movk/nuxt-docs@^3.0.0
```

## Change list

### 1. Dependencies of optional features

These features no longer bring their dependencies with the layer. Install only for the features the project actually uses:

| Feature | Enabled when | Install |
|---|---|---|
| Component docs | Pages use `ComponentProps` / `ComponentSlots` / `ComponentEmits` / `ComponentCode` / `ComponentExample` | `nuxt-component-meta vue-component-meta prettier`, and set `movkNuxtDocs.componentDocs: true` |
| AI Chat | `AI_API_KEY` is present at build time, or `aiChat.enabled: true` | `ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes` |
| Mermaid | `movkNuxtDocs.mermaid` is on | `mermaid dompurify` (v2 silently skipped missing dependencies, v3 fails the build) |
| Accessibility checks | On by default in v2, off in v3 | If needed, set `movkNuxtDocs.a11y: true` and install `@nuxt/a11y` |
| i18n | `modules` includes `@nuxtjs/i18n` | `@nuxtjs/i18n` |

To tell whether component docs are used, search `content/` and `app/` for the component names above.

### 2. AI Chat and MCP

With AI Chat enabled, `movkNuxtDocs.mcp: false` fails the build. If both are present, remove `mcp: false`.

### 3. Content directory

Docs must live in `content/docs/`, other languages in `content/{locale}/docs/`, and the route prefix is always `/docs`. If docs sit directly under `content/` (e.g. `content/1.getting-started/`), move them into `content/docs/` and update paths in internal links, `header.nav`, `docs.categories` and similar places. `content/index.md`, `content/releases.*` and `content/templates.*` stay at the root of `content/`.

### 4. Config fields

- `github.per_page` in `app.config.ts` is renamed to `github.perPage`
- v2 only showed commits after `2025-01-31` and before build time; v3 applies no filter. If the site relied on that, set `github.since` / `github.until` explicitly

### 5. Removed author-specific defaults

v3 no longer ships these defaults. If the site depends on them, set them explicitly in the project config:

- `header.avatar` (pointed to the author's avatar in v2)
- `github.dateFormat.options.timeZone: 'Asia/Shanghai'`
- The Alibaba PuHuiTi font CDN: the font stack still prefers that font, so load its stylesheet through `app.head.link` if needed

### 6. Visual defaults (ask me first)

| Item | v2 | v3 | Restore v2 |
|---|---|---|---|
| Primary / neutral color | `green` / `slate` | `vermilion` / `paper` | In `app.config.ts`, set `ui.colors.primary: 'green'` and `ui.colors.neutral: 'slate'` |
| Heading font | Sans-serif | Serif (Fraunces) | `theme.font: 'sans'` |
| Code highlighting | Nuxt Content default | `github-light` / `github-dark` | Set `content.build.markdown.highlight.theme` in `nuxt.config.ts` |

Colors, fonts and highlight themes the project already sets explicitly stay unchanged.

### 7. Component overrides

Look in `app/components/` for overrides with the same name as layer components:

- The override contract table on the Customization page lists the overridable components, mount points and props. Components not listed there (such as `ThemePickerButton`) are internal; flag them for me to review
- The header, sidebar, table of contents, prev/next links and footer are redesigned. Flag overrides of these components, and CSS that depends on their DOM structure, for me to review
- `PageHeaderLinks` now mounts in the meta row below the lead paragraph of doc pages
- The layer overrides Nuxt UI's `ProsePre`; a `ProsePre` override in the project still wins and needs no change

### 8. Removed APIs

- Remove every reference to the `HeroBackground` component and the `heroBackground` key in `definePageMeta({ heroBackground: ... })`
- If the project overrides `useToolCall`, change the `state` parameter type from `ToolState` to `string` and drop the unused `ToolState` import

## Verification

1. Run `nuxt build`. If it reports enabled features with missing dependencies, install them as instructed; `[request error]` logs mean dead links, so fix those links
2. Run the project's typecheck and tests
3. Start the dev server and spot-check the home page, a doc page and a page that uses component docs
````

## 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](https://docs.mhaibaraai.cn/en/docs/guide/features) for details.

### Component docs are off by default

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

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

```bash [Install]
pnpm add nuxt-component-meta vue-component-meta prettier
```

### 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:

```bash
# 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:

```bash
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:

```ts [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.

```bash
# 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`

```diff [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:

```ts [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 default | v3 default | How to restore |
| --- | --- | --- |
| `header.avatar` pointing to the author's avatar | `''` | Set `header.avatar` |
| `github.dateFormat.options.timeZone: 'Asia/Shanghai'` | No time zone | Set `timeZone` in `github.dateFormat.options` |
| Loads the Alibaba PuHuiTi font CDN | Not loaded | See [Fonts](#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.

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

```ts [v3 app/app.config.ts]
export default defineAppConfig({
  header: {
    nav: [
      { label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started', activeMatch: '/docs' }
    ]
  },
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
```

See [Navigation and Categories](https://docs.mhaibaraai.cn/en/docs/guide/navigation) 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:

```ts [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:

```ts [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:

```ts [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](https://docs.mhaibaraai.cn/en/docs/guide/theme) 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:

```ts [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](https://docs.mhaibaraai.cn/en/docs/guide/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:

```diff [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:

```diff [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>) {
```


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
