Migrating from v2
- Requires
- @movk/nuxt-docs 3.0
- Difficulty
- Intermediate
Upgrade steps
- Upgrade
@movk/nuxt-docsto^3.0.0 - Install the optional dependencies you use, see Dependencies and feature flags
- Make sure your docs live in
content/docs/ - Review
app.config.tsand any overridden components - 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.
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 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
}
})
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:
# 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:
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
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:
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 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 }
}
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 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:
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:
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:
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:
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
PageHeaderLinksmoves 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:
<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:
-export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
+export function useToolCall(state: string, toolName: string, input: Record<string, string | undefined>) {
Project Structure
What each directory and file does in a Movk Nuxt Docs project, where content goes, how routes are generated, which files turn into the releases and showcase pages, and what the two config files control.
Configuration Overview
Movk Nuxt Docs is configured in two places. nuxt.config.ts decides at build time which modules and features are included; app.config.ts controls UI, text and navigation at runtime. This page explains the split, when each takes effect, and where common changes belong.