配置文档站点

查看源码
通过 app.config.ts 自定义 SEO 元数据、头部导航、页脚版权、侧边栏导航过滤和 AI Chat 界面，通过 nuxt.config.ts 配置 GitHub 集成、组件元数据生成、Mermaid 图表和无障碍功能等模块级选项的完整参考。

应用配置

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

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',
      }],
    },
  },
})

侧边栏 (Aside)

为左侧导航开启过滤框，便于在条目较多的文档区段中快速定位。过滤框默认关闭，启用后仅当当前分组导航项总数达到 threshold 时才显示，并固定在侧边栏顶部（随导航滚动保持可见）。过滤按导航项的标题与描述匹配，切换页面时自动清空。

app/app.config.ts
export default defineAppConfig({
  aside: {
    filter: {
      // 启用导航过滤框
      enabled: true,
      // 过滤框占位文本
      placeholder: '过滤导航...',
      // 导航项总数达到该值时才显示过滤框
      threshold: 10,
      // 聚焦过滤框的快捷键，留空则禁用
      shortcut: '/',
    },
  },
})

配置属性：

属性类型默认值描述
filter.enabledbooleanfalse是否在侧边栏顶部显示导航过滤框
filter.placeholderstring'过滤导航...'过滤框的占位提示文本
filter.thresholdnumber10当前分组导航项总数达到该值时才显示过滤框
filter.shortcutstring'/'聚焦过滤框的键盘快捷键，留空则禁用

Layer 功能开关（movkNuxtDocs）

Movk Nuxt Docs 在 nuxt.config.ts 中提供 movkNuxtDocs 配置组，用于控制可选功能模块。

nuxt.config.ts
export default defineNuxtConfig({
  movkNuxtDocs: {
    a11y: true,
    mermaid: false
  },
})
选项默认值说明
a11ytrue是否启用 @nuxt/a11y 无障碍支持。
mermaidfalse是否启用 Mermaid 图表渲染（需安装 mermaid 与 dompurify）。
查看 Mermaid 文档了解图表语法与完整用法。

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 解释此页面」按钮
faqQuestions`FaqQuestionsLocalizedFaqQuestions`{lang="ts-type"}[]
shortcuts.focusInputstring'meta_i'聚焦浮动输入框的快捷键

文本配置

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

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    texts: {
      title: 'AI 助手',
      clearChat: '清除聊天记录',
      close: '关闭',
      placeholder: '输入你的问题...',
      lineBreak: '换行',
      trigger: '与 AI 聊天',
      explainWithAi: '用 AI 解释此页面'
    }
  }
})

图标配置

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

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    icons: {
      trigger: 'i-custom-ai',
      explain: 'i-lucide-bot-message-square',
      reasoning: 'i-lucide-brain',
      close: 'i-lucide-panel-right-close',
      clearChat: 'i-lucide-list-x',
      providers: {
        deepseek: 'i-hugeicons:deepseek',
        alibaba: 'i-hugeicons:qwen',
        zai: 'i-simple-icons:zig',
        moonshotai: 'i-hugeicons:kimi-ai',
        xai: 'i-hugeicons:grok-02'
      }
    }
  }
})

FAQ 问题格式

分类格式（推荐）：

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

简单格式：

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

本地化格式（多语言）： v2+

启用 i18n 时，可按语言代码分组，面板会根据当前语言自动选择对应问题（缺失时回退到默认语言）。每种语言均支持上述简单或分类格式。

app/app.config.ts
export default defineAppConfig({
  aiChat: {
    faqQuestions: {
      'zh-CN': [
        { category: '快速开始', items: ['如何安装？', '如何配置？'] }
      ],
      'en': [
        { category: 'Getting Started', items: ['How to install?', 'How to configure?'] }
      ]
    }
  }
})

组件元数据配置

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 模块，提供：

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

默认启用，可通过 movkNuxtDocs.a11y 关闭：

nuxt.config.ts
export default defineNuxtConfig({
  movkNuxtDocs: {
    a11y: false,
  },
})

语义化 HTML：

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

键盘导航：

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

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

故障排除

解决使用 Movk Nuxt Docs 时遇到的常见问题，包括 Google Fonts 访问、pnpm shamefully-hoist 配置移除、Tailwind CSS peer dependency 安装、构建脚本审批，以及 Vercel 部署 OOM 内存不足等问题的详细解决方案。

自定义

在 components/ 目录中创建同名 Vue 文件即可覆盖内置组件。涵盖头部 Logo、桌面端导航菜单、移动端抽屉、页脚、左侧/右侧侧边栏插槽及主题选择器等所有界面区域的完整自定义指南，附默认组件源码链接。

Copyright © 2024 - 2026