Troubleshooting
Build fails with "已启用的功能缺少依赖"
[@movk/nuxt-docs] 已启用的功能缺少依赖:
- mermaid: mermaid, dompurify
请安装后重试:pnpm add mermaid dompurify
AI Chat, component docs, Mermaid and a11y are off by default, and their dependencies are optional peer dependencies of the layer that are not installed automatically. When you turn one on, the layer checks its dependencies before the build starts and stops with an install command if any are missing. The message reads "enabled features are missing dependencies"; run the command it prints. See Feature Flags for each feature's packages:
| Feature | Packages to install |
|---|---|
| AI Chat | ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes |
| Component docs | nuxt-component-meta vue-component-meta prettier |
| Mermaid | mermaid dompurify |
| a11y | @nuxt/a11y |
AI Chat turns on automatically when AI_API_KEY exists in the build environment, so if CI has that variable you need the AI Chat packages; set aiChat.enabled: false if you do not want it.
Build fails with "aiChat 依赖 MCP Server"
[@movk/nuxt-docs] aiChat 依赖 MCP Server,请勿在启用 aiChat 时设置 movkNuxtDocs.mcp: false
The message means "aiChat depends on the MCP Server; do not set movkNuxtDocs.mcp: false while aiChat is enabled". AI Chat searches the docs through the site's own MCP Server, so the two cannot be separated. Keep MCP, or turn AI Chat off as well:
export default defineNuxtConfig({
aiChat: {
enabled: false
},
movkNuxtDocs: {
mcp: false
}
})
Every docs page returns 404
This warning at build time means the layer found no docs directory:
[@movk/nuxt-docs] 未找到 content/docs 目录,文档页面固定位于 /docs 下,请将文档放入 content/docs/
Docs must live in content/docs/ and are always served under /docs; in multilingual sites other locales go in content/{code}/docs/. Move your docs there. Numeric prefixes in file names only control ordering and do not appear in URLs. See Project Structure.
Build fails after enabling multiple languages
When an entry in i18n.locales declares file, @nuxtjs/i18n looks for translation files in your site's own i18n/locales/ directory and fails when they are missing. Remove file and keep only code and name:
export default defineNuxtConfig({
i18n: {
defaultLocale: 'zh-CN',
locales: [
{ code: 'zh-CN', name: '简体中文' },
{ code: 'en', name: 'English' }
]
}
})
A locale has no effect
If the build log warns about a missing translation file (缺少翻译文件) or a missing content directory (缺少内容目录), that locale was skipped:
[movk-docs] 缺少内容目录 content/en/,已跳过 locale "en"
A non-default locale needs both a translation file shipped with the layer (currently zh-CN and en) and a content/{code}/ directory. See Internationalization.
Image processing fails after a pnpm install
pnpm does not run dependency install scripts by default, and sharp, used by @nuxt/image, has to be allowed explicitly. Declare it in pnpm-workspace.yaml at the project root:
allowBuilds:
sharp: true
You can also run pnpm approve-builds and pick it interactively. Run pnpm install again afterwards. The official templates already include this setting.
allowBuilds; older settings such as onlyBuiltDependencies were removed. See the pnpm docs.Missing peer dependency tailwindcss
WARN Issues with peer dependencies found
└─┬ @movk/nuxt-docs
└── ✕ missing peer tailwindcss@4.x
nuxt, @nuxt/content and tailwindcss are required peer dependencies and must be installed in your project:
pnpm add nuxt @nuxt/content tailwindcss
npm install nuxt @nuxt/content tailwindcss
yarn add nuxt @nuxt/content tailwindcss
bun add nuxt @nuxt/content tailwindcss
Commit history and last updated time are missing
CommitChangelog and PageLastCommit request GitHub data from the browser. Check, in order:
- Whether
NUXT_GITHUB_TOKENis set in the runtime environment. Without a token the endpoints return empty results; - Whether
github.owner,github.nameandgithub.branchinapp.configmatch the repository. When they are unset the layer infers them from Git, and there is no data if that fails; - Whether
github.rootDirpoints to the docs directory when the docs are not at the repository root; - Whether the site is deployed as static files. A static site has no
/api/github/*endpoints; see Deployment.
AI Chat does not appear
Whether AI Chat is bundled is decided at build time: the build environment needs AI_API_KEY, or aiChat.enabled: true in nuxt.config.ts. Setting the variable only at runtime does not add AI Chat to an existing build; rebuild after configuring it. See AI Chat.
Google Fonts requests fail
Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left.
The layer sets ui.fonts: false and self-hosts Inter, Fraunces and JetBrains Mono, so it never requests Google Fonts. This warning means @nuxt/fonts was turned back on in your project; turn it off again:
export default defineNuxtConfig({
ui: {
fonts: false
}
})
To add Chinese fonts, see Theme & Fonts.
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.
FAQ
Answers to common questions about Movk Nuxt Docs, from how it relates to the Nuxt UI docs template, package managers and Node.js versions, and single-language sites, to turning off GitHub, using other AI providers, upgrading, overriding components and static hosting limits.