配置总览
Movk Nuxt Docs 的配置分为 nuxt.config.ts 与 app.config.ts 两处:前者在构建期决定启用哪些模块与功能,后者在运行时控制界面、文案与导航。本页说明两者的分工、生效时机,以及常见需求应该改哪一处。
两个配置文件
| 文件 | 生效时机 | 负责内容 | 完整参考 |
|---|---|---|---|
nuxt.config.ts | 构建期 | 继承 Layer、功能开关、AI 模型、MCP、llms.txt、国际化、站点地址 | nuxt.config 选项 |
app/app.config.ts | 运行时 | 页头、页脚、导航、侧栏分类、目录、主题、GitHub 集成、AI Chat 界面文案 | app.config 参考 |
判断改哪一处的规则很简单:会影响打包了哪些代码、生成哪些路由与文件的,放 nuxt.config.ts;只影响页面上显示什么的,放 app.config.ts。
最小配置
继承 Layer 后,大多数站点只需要补充站点名称与导航:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
site: {
name: 'My Docs',
url: 'https://docs.example.com'
}
})
export default defineAppConfig({
header: {
nav: [
{ label: '文档', to: '/docs/getting-started', activeMatch: '/docs' },
{ label: '版本发布', to: '/releases' }
]
},
footer: {
credits: 'Copyright © 2026 My Team'
}
})
未配置的字段使用 Layer 的默认值。以下几项会在构建期自动推断:
| 字段 | 来源 |
|---|---|
site.name | package.json 的 name,其次是 Git 仓库名 |
site.url | NUXT_PUBLIC_SITE_URL、NUXT_SITE_URL,或 Vercel、Netlify、Cloudflare Pages、GitLab Pages 注入的部署地址 |
header.title | site.name 转为首字母大写 |
seo.title / seo.titleTemplate | site.name,标题模板为 %s - {site.name} |
seo.description | package.json 的 description |
github.owner / name / url / branch | 本地 Git 信息或 CI 环境变量 |
常见任务
| 想做的事 | 改哪里 | 详见 |
|---|---|---|
| 修改页头导航、移动端菜单、侧栏分组 | app.config 的 header.nav、header.mobileNav、docs.categories | 导航与分类 |
| 更换主色、中性色、标题字体 | app.config 的 ui.colors、theme.* | 主题与字体 |
| 启用组件文档、Mermaid、AI Chat | nuxt.config 的 movkNuxtDocs.*、aiChat.* | 功能开关 |
| 替换页头 Logo、页脚等界面区域 | 在 app/components/ 中创建同名组件 | 自定义 |
| 添加版本发布页、案例页、自定义页面 | content/releases.yml、content/templates.yml、app/pages/ | 页面与布局 |
| 支持多语言 | nuxt.config 的 i18n | 国际化 |
SEO
全站默认值写在 app.config.ts,单页覆盖写在 Markdown 的 frontmatter:
export default defineAppConfig({
seo: {
titleTemplate: '%s - My Docs',
title: 'My Docs',
description: '一句话介绍你的项目'
}
})
---
title: 简介
description: 页面导语,同时作为默认的 meta description。
seo:
title: Introduction
description: 搜索引擎与社交卡片使用的描述。
---
文档页的 <title> 与 OG 图片优先使用 seo.title,未设置时回退到 title;描述同理。
GitHub 集成
Layer 从本地 Git 信息推断仓库地址,用于页头 GitHub 图标、「查看源码 / 编辑此页」链接、PageLastCommit 与 CommitChangelog。文档不在仓库根目录时需要指定 rootDir:
app/app.config.ts
export default defineAppConfig({
github: {
rootDir: 'docs',
branch: 'main'
}
})
设置 github: false 可完全关闭集成。生产环境请配置 NUXT_GITHUB_TOKEN,避免 GitHub API 匿名请求的频率限制。
目录与页脚
app/app.config.ts
export default defineAppConfig({
toc: {
title: '本页内容',
bottom: {
title: '社区',
links: [
{ icon: 'i-lucide-book-open', label: 'Nuxt UI', to: 'https://ui.nuxt.com', target: '_blank' }
]
}
},
footer: {
credits: 'Copyright © 2026 My Team · <span class="text-highlighted">MIT License</span>',
socials: [
{ 'icon': 'i-simple-icons-github', 'to': 'https://github.com/my/repo', 'target': '_blank', 'aria-label': 'GitHub' }
]
}
})
footer.credits 按 MDC 渲染,可以包含链接与行内 HTML。目录底部会自动追加 GitHub 的「编辑此页」链接。