Site Logo

Movk Nuxt Docs

配置

View source
通过 app.config.ts 和 nuxt.config.ts 自定义文档站点。

应用配置

覆盖 app/app.config.ts 需要同时创建 nuxt.config.ts 文件。

Vercel Analytics

在 app/app.config.ts 中启用 Vercel Analytics：

app/app.config.ts
export default defineAppConfig({
  vercelAnalytics: {
    enable: true,
    debug: false
  },
})

SEO

全局配置

在 app/app.config.ts 中定义默认 SEO 元数据。

site.name 可在 nuxt.config.ts 中配置，默认值来自 package.json 的 name 字段。

export default defineAppConfig({
  seo: {
    // 默认为 `%s - ${site.name}`
    titleTemplate: '',
    // 默认为 package.json 的 name 字段
    title: '',
    // 默认为 package.json 的 description 字段
    description: '',
  },
})

按页面配置

在 Markdown 文件的 Front-Matter 中定义 SEO 元数据：

md] [content/concepts/configuration.md
---
seo:
  title: '配置'
  description: '通过 Nuxt 应用配置文件自定义文档。'
---

<!-- 页面内容 -->
查看 Nuxt Content Front-Matter 文档。

头部 (Header)

app/app.config.ts
export default defineAppConfig({
  header: {
    title: '', // 标题
    avatar: '', // 头像链接
    to: '/', // 标题链接
    search: true, // 显示搜索栏
    colorMode: true, // 显示颜色模式切换器
    links: ButtonProps[], // 头部链接按钮
  },
})

页脚 (Footer)

app/app.config.ts
export default defineAppConfig({
  footer: {
    // 版权信息
    credits: `Copyright © 2024 - ${new Date().getFullYear()} YiXuan - <span class="text-highlighted">MIT License</span>`,
    // 页脚社交媒体图标链接
    socials: [
      {
        icon: 'i-lucide-brain',
        to: 'https://docs.mhaibaraai.cn/llms.txt',
        target: '_blank',
        label: 'Open LLMs',
      },
    ],
  },
})

目录 (TOC)

您可以自定义每个页面右侧的内容目录（Table of Contents）。

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/getting-started/installation/nuxt',
        target: '_blank',
      }],
    },
  },
})

GitHub 集成

使用 git-url-parse 自动获取仓库信息，提供以下功能：

  • 头部和页脚的 GitHub 图标链接
  • 目录底部的「在 GitHub 上编辑」和「报告问题」链接
  • CommitChangelog 组件的提交历史

基础配置

在 app/app.config.ts 中配置 GitHub 集成：

app/app.config.ts
export default defineAppConfig({
  github: {
    branch: 'main',
    rootDir: 'docs',
  },
})

完整配置属性：

属性类型默认值描述
ownerstring自动检测仓库所有者用户名
namestring自动检测仓库名称
urlstring自动检测仓库完整 URL
branchstring自动检测Git 分支名称
rootDirstring-文档根目录路径
commitPathstring'src'组件文件所在的基础路径
suffixstring'vue'组件文件的默认扩展名
casing'auto' | 'kebab' | 'camel' | 'pascal''auto' vue 文件用 PascalCase，其他用 camelCase文件命名格式
sincestring'2025-01-31T04:00:00Z'提交历史的起始时间(ISO 8601 格式)
untilstring当前时间提交历史的截止时间(ISO 8601 格式)
per_pagenumber100每次请求获取的提交数量 (1-100)
authorstring-按作者过滤提交记录，可使用 GitHub 用户名或邮箱
dateFormatobject{ locale: 'zh-CN', options: {...} }日期格式化配置
commitPath、suffix、casing、since、until、per_page、author 用于 CommitChangelog 组件。dateFormat 用于 PageLastCommit 组件。查看 CommitChangelog 文档了解详情。

禁用 GitHub 集成

设置 github: false 禁用 GitHub 集成：

app/app.config.ts
export default defineAppConfig({
  github: false,
})

AI Chat 配置

查看完整的 AI Chat 功能文档

在 app/app.config.ts 中配置 AI Chat 的界面文本、图标、快捷键和 FAQ 问题。

基础配置

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    // 是否显示浮动输入框
    floatingInput: true,
    // 是否显示「用 AI 解释此页面」按钮
    explainWithAi: true,
    // FAQ 问题列表
    faqQuestions: [
      {
        category: '快速开始',
        items: ['如何安装？', '如何配置？']
      }
    ],
    // 键盘快捷键
    shortcuts: {
      focusInput: 'meta_i' // ⌘I / Ctrl+I
    }
  }
})

配置属性：

属性类型默认值描述
floatingInputbooleantrue在文档页面底部显示浮动输入框
explainWithAibooleantrue在文档侧边栏显示「用 AI 解释此页面」按钮
faqQuestionsFaqQuestions[]FAQ 问题列表，支持分类和简单两种格式
shortcuts.focusInputstring'meta_i'聚焦浮动输入框的快捷键

文本配置

自定义 AI Chat 界面中的所有文本：

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    texts: {
      title: 'AI 助手',
      collapse: '折叠',
      expand: '展开',
      clearChat: '清除聊天记录',
      close: '关闭',
      loading: 'Loading...',
      askAnything: '问我任何事情...',
      askMeAnythingDescription: '我可以帮助您浏览文档、解释概念并回答您的问题。',
      faq: 'FAQ 建议',
      placeholder: '输入你的问题...',
      lineBreak: '换行',
      trigger: '与 AI 聊天',
      streaming: '思考中...',
      streamed: '思考过程',
      explainWithAi: '用 AI 解释此页面'
    }
  }
})

图标配置

自定义 AI Chat 界面中的所有图标：

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    icons: {
      loading: 'i-lucide-loader',
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain',
      close: 'i-lucide-x',
      clearChat: 'i-lucide-trash-2',
      streaming: 'i-lucide-chevron-down',
      providers: {
        mistral: 'i-simple-icons-mistralai',
        kwaipilot: 'i-lucide-wand',
        zai: 'i-lucide-wand'
      }
    }
  }
})

FAQ 问题格式

FAQ 问题支持两种格式：

分类格式（推荐）：

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    faqQuestions: [
      {
        category: '快速开始',
        items: ['如何安装？', '如何配置？']
      },
      {
        category: '进阶使用',
        items: ['如何自定义？', '如何部署？']
      }
    ]
  }
})

简单格式：

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    faqQuestions: [
      '如何安装？',
      '如何配置？',
      '如何自定义？'
    ]
  }
})

组件元数据配置

Movk Nuxt Docs 使用 nuxt-component-meta 自动生成组件文档（Props、Slots、Emits）。

默认行为

为避免生成不必要的文档，以下路径中的组件默认被排除：

  • app/components/、components/、docs/app/components/、templates/*/app/components/
只有通过 componentMeta.include 显式指定的组件才会生成文档。

配置示例

nuxt.config.ts
export default defineNuxtConfig({
  componentMeta: {
    // 支持字符串 glob、正则表达式或函数
    include: [
      'Button',              // 精确匹配
      'Card*',               // 匹配 Card 开头的组件
      /^Modal/,              // 正则表达式
      ({ pascalName }) => pascalName.endsWith('Input')
    ],
    // 可选：额外排除规则
    exclude: [
      'Internal*',
      /Test$/
    ]
  }
})

glob 语法： * 匹配字符（不含 /），** 匹配任意路径。

查看 nuxt-component-meta 完整文档了解更多配置选项和高级用法。

无障碍功能

Movk Nuxt Docs v1.7.0+ 内置了无障碍支持，确保文档站点对所有用户都可访问。

内置支持

@nuxt/a11y 模块：

Movk Nuxt Docs 已集成 @nuxt/a11y 模块，提供：

  • 自动化无障碍检查
  • 路由变更时的焦点管理
  • 键盘导航支持
  • 屏幕阅读器优化

语义化 HTML：

  • 使用 <main> 标签包裹主内容区域
  • 使用适当的标题层级（<h1> - <h6>）
  • 为交互元素添加 aria-label 属性

键盘导航：

所有交互元素都支持键盘导航：

快捷键功能
⌘I / Ctrl+I聚焦 AI Chat 浮动输入框
Enter提交问题
Escape关闭面板或失焦输入框
Tab在可聚焦元素间切换
了解更多关于 @nuxt/a11y 模块的配置选项

项目结构

Movk Nuxt Docs 项目结构和目录说明。

自定义

通过覆盖内置组件自定义文档外观。

Copyright © 2024 - 2026