---
title: "配置文档站点"
description: "通过 app.config.ts 自定义 SEO 元数据、头部导航、页脚版权、侧边栏导航过滤和 AI Chat 界面，通过 nuxt.config.ts 配置 GitHub 集成、组件元数据生成、Mermaid 图表和无障碍功能等模块级选项的完整参考。"
seo_title: "Configuration"
seo_description: "Configure Movk Nuxt Docs with app.config.ts for SEO and UI settings, and nuxt.config.ts for GitHub, component metadata, Mermaid, and a11y modules."
canonical_url: "https://docs.mhaibaraai.cn/docs/getting-started/configuration"
---
# 配置文档站点

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

## 应用配置

> \[\!WARNING\]
> See: https://nuxt.com/docs/4.x/directory-structure/app/app-config
> 
> 覆盖 
> 
> app/app.config.ts
> 
>  需要同时创建 
> 
> nuxt.config.ts
> 
>  文件。

### SEO

#### 全局配置

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

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

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  site: {
    name: 'Movk Nuxt Docs',
  },
})
```

#### 按页面配置

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

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

<!-- 页面内容 -->
```

> \[\!TIP\]
> See: https://content.nuxt.com/docs/collections/types#page-type
> 
> 查看 Nuxt Content Front-Matter 文档。

### 头部 (Header)

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

### 页脚 (Footer)

```ts [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）。

```ts [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` 时才显示，并固定在侧边栏顶部（随导航滚动保持可见）。过滤按导航项的标题与描述匹配，切换页面时自动清空。

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

**配置属性：**

| 属性                   | 类型        | 默认值         | 描述                   |
| -------------------- | --------- | ----------- | -------------------- |
| `filter.enabled`     | `boolean` | `false`     | 是否在侧边栏顶部显示导航过滤框      |
| `filter.placeholder` | `string`  | `'过滤导航...'` | 过滤框的占位提示文本           |
| `filter.threshold`   | `number`  | `10`        | 当前分组导航项总数达到该值时才显示过滤框 |
| `filter.shortcut`    | `string`  | `'/'`       | 聚焦过滤框的键盘快捷键，留空则禁用    |

## Layer 功能开关（movkNuxtDocs）

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movkNuxtDocs: {
    a11y: true,
    mermaid: false
  },
})
```

| 选项        | 默认值     | 说明                                              |
| --------- | ------- | ----------------------------------------------- |
| `a11y`    | `true`  | 是否启用 `@nuxt/a11y` 无障碍支持。                        |
| `mermaid` | `false` | 是否启用 Mermaid 图表渲染（需安装 `mermaid` 与 `dompurify`）。 |

> \[\!TIP\]
> See: /docs/typography/mermaid
> 
> 查看 Mermaid 文档了解图表语法与完整用法。

## GitHub 集成

使用 [git-url-parse](https://github.com/IonicaBizau/git-url-parse){rel="[\"nofollow\"]"} 自动获取仓库信息，提供以下功能：

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

### 基础配置

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

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

**完整配置属性：**

| 属性           | 类型                                      | 默认值                                       | 描述                          |
| ------------ | --------------------------------------- | ----------------------------------------- | --------------------------- |
| `owner`      | `string`                                | 自动检测                                      | 仓库所有者用户名                    |
| `name`       | `string`                                | 自动检测                                      | 仓库名称                        |
| `url`        | `string`                                | 自动检测                                      | 仓库完整 URL                    |
| `branch`     | `string`                                | 自动检测                                      | Git 分支名称                    |
| `rootDir`    | `string`                                | -                                         | 文档根目录路径                     |
| `commitPath` | `string`                                | `'src'`                                   | 组件文件所在的基础路径                 |
| `suffix`     | `string`                                | `'vue'`                                   | 组件文件的默认扩展名                  |
| `casing`     | `'auto' | 'kebab' | 'camel' | 'pascal'` | `'auto'` vue 文件用 PascalCase，其他用 camelCase | 文件命名格式                      |
| `since`      | `string`                                | `'2025-01-31T04:00:00Z'`                  | 提交历史的起始时间(ISO 8601 格式)      |
| `until`      | `string`                                | 当前时间                                      | 提交历史的截止时间(ISO 8601 格式)      |
| `per_page`   | `number`                                | `100`                                     | 每次请求获取的提交数量 (1-100)         |
| `author`     | `string`                                | -                                         | 按作者过滤提交记录，可使用 GitHub 用户名或邮箱 |
| `dateFormat` | `object`                                | `{ locale: 'zh-CN', options: {...} }`     | 日期格式化配置                     |

> \[\!TIP\]
> See: /docs/components/commit-changelog
> 
> commitPath
> 
> 、
> 
> suffix
> 
> 、
> 
> casing
> 
> 、
> 
> since
> 
> 、
> 
> until
> 
> 、
> 
> per\_page
> 
> 、
> 
> author
> 
>  用于 
> 
> CommitChangelog
> 
>  组件。
> 
> dateFormat
> 
>  用于 
> 
> PageLastCommit
> 
>  组件。查看 CommitChangelog 文档了解详情。

### 禁用 GitHub 集成

设置 `github: false` 禁用 GitHub 集成：

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

## AI Chat 配置

> \[\!TIP\]
> See: /docs/getting-started/ai-chat
> 
> 查看完整的 AI Chat 功能文档

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

### 基础配置

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

**配置属性：**

| 属性                     | 类型             | 默认值                                     | 描述                     |
| ---------------------- | -------------- | --------------------------------------- | ---------------------- |
| `floatingInput`        | `boolean`      | `true`                                  | 在文档页面底部显示浮动输入框         |
| `explainWithAi`        | `boolean`      | `true`                                  | 在文档侧边栏显示「用 AI 解释此页面」按钮 |
| `faqQuestions`         | \`FaqQuestions | LocalizedFaqQuestions\`{lang="ts-type"} | `[]`                   |
| `shortcuts.focusInput` | `string`       | `'meta_i'`                              | 聚焦浮动输入框的快捷键            |

### 文本配置

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

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

### 图标配置

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

```ts [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 问题格式

**分类格式（推荐）：**

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

**简单格式：**

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

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

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

```ts [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`](https://github.com/nuxt-content/nuxt-component-meta){rel="[\"nofollow\"]"} 自动生成组件文档（Props、Slots、Emits）。

### 默认行为

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

- `app/components/`、`components/`、`docs/app/components/`、`templates/*/app/components/`

> \[\!WARNING\]
> 
> 只有通过 
> 
> componentMeta.include
> 
>  显式指定的组件才会生成文档。

### 配置示例

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

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

> \[\!TIP\]
> See: https://github.com/nuxt-content/nuxt-component-meta
> 
> 查看 
> 
> nuxt-component-meta
> 
>  完整文档了解更多配置选项和高级用法。

## 无障碍功能

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

### 内置支持

**@nuxt/a11y 模块：**

Movk Nuxt Docs 默认集成 [@nuxt/a11y](https://a11y.nuxtjs.org/){rel="[\"nofollow\"]"} 模块，提供：

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

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

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

**语义化 HTML：**

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

**键盘导航：**

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

| 快捷键             | 功能               |
| --------------- | ---------------- |
| `⌘I` / `Ctrl+I` | 聚焦 AI Chat 浮动输入框 |
| `Enter`         | 提交问题             |
| `Escape`        | 关闭面板或失焦输入框       |
| `Tab`           | 在可聚焦元素间切换        |

> \[\!TIP\]
> See: https://github.com/nuxt/a11y
> 
> 了解更多关于 @nuxt/a11y 模块的配置选项


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.