配置总览

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。

app.config.ts 需要位于 app/ 目录下,并且项目根目录必须存在 nuxt.config.ts。

最小配置

继承 Layer 后,大多数站点只需要补充站点名称与导航:

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  site: {
    name: 'My Docs',
    url: 'https://docs.example.com'
  }
})

未配置的字段使用 Layer 的默认值。以下几项会在构建期自动推断:

字段来源
site.namepackage.json 的 name,其次是 Git 仓库名
site.urlNUXT_PUBLIC_SITE_URL、NUXT_SITE_URL,或 Vercel、Netlify、Cloudflare Pages、GitLab Pages 注入的部署地址
header.titlesite.name 转为首字母大写
seo.title / seo.titleTemplatesite.name,标题模板为 %s - {site.name}
seo.descriptionpackage.json 的 description
github.owner / name / url / branch本地 Git 信息或 CI 环境变量

常见任务

想做的事改哪里详见
修改页头导航、移动端菜单、侧栏分组app.config 的 header.nav、header.mobileNav、docs.categories导航与分类
更换主色、中性色、标题字体app.config 的 ui.colors、theme.*主题与字体
启用组件文档、Mermaid、AI Chatnuxt.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> 与 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 匿名请求的频率限制。

github.since、github.perPage、github.dateFormat 等全部字段见 app.config 参考。

目录与页脚

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 的「编辑此页」链接。

Copyright © 2024 - 2026