# Movk Nuxt Docs ::u-page-hero --- ui: container: lg:py-20 class: dark:bg-gradient-to-b from-neutral-900 to-neutral-950 orientation: horizontal --- :::motion --- transition: duration: 0.6 delay: 0.1 class: mx-auto --- ::::prose-pre --- code: | export default defineNuxtConfig({ extends: ['@movk/nuxt-docs'], css: ['~/assets/css/main.css'], aiChat: { model: 'mistral/devstral-2', models: ['mistral/devstral-2', 'openrouter/qwen/qwen3-4b:free'] }, mcp: { name: 'My Docs' } }) filename: nuxt.config.ts --- ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@movk/nuxt-docs'], css: ['~/assets/css/main.css'], aiChat: { model: 'mistral/devstral-2', models: ['mistral/devstral-2', 'openrouter/qwen/qwen3-4b:free'] }, mcp: { name: 'My Docs' } }) ``` :::: ::: #top :hero-background #title :::motion 构建现代智能的 [文档]{.text-primary} ::: #description :::motion --- transition: duration: 0.6 delay: 0.3 --- 基于 Nuxt 4 的现代文档主题，集成组件自动化文档、AI 聊天助手、MCP Server 和完整的开发者体验优化，助您轻松构建美观、专业、智能的文档网站。 ::: #links :::motion --- transition: duration: 0.6 delay: 0.5 class: flex flex-wrap gap-x-6 gap-y-3 --- ::::u-button --- size: xl to: https://docs.mhaibaraai.cn/docs/getting-started trailing-icon: i-lucide-arrow-right --- 快速入门 :::: ::::u-button --- color: neutral icon: i-simple-icons-github size: xl target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs variant: outline --- 使用模板 :::: ::: :: ::u-page-section --- class: dark:bg-neutral-950 --- #title 自动化文档生成 #links :::u-button --- color: neutral size: lg to: https://docs.mhaibaraai.cn/docs/components trailingIcon: i-lucide-arrow-right variant: subtle --- 查看组件文档 ::: #features :::u-page-feature --- icon: i-lucide-file-code --- #title 组件元数据自动提取 #description 基于 `nuxt-component-meta` 自动提取 Vue 组件的 Props、Slots、Emits 定义，无需手动维护文档。 ::: :::u-page-feature --- icon: i-lucide-code --- #title 交互式示例展示 #description 通过 `ComponentExample` 组件自动加载和渲染组件示例，支持代码高亮和实时预览。 ::: :::u-page-feature --- icon: i-lucide-git-commit --- #title Git 提交历史集成 #description 使用 `CommitChangelog` 和 `PageLastCommit` 组件自动展示文件的提交历史记录和最后更新时间。 ::: :::u-page-feature --- icon: i-lucide-palette --- #title 类型定义高亮 #description 智能解析 TypeScript 类型定义，支持内联类型高亮和类型导航，提升 API 文档可读性。 ::: :::u-page-feature --- icon: i-lucide-layers --- #title 丰富的文档组件 #description 内置 Accordion、Callout、Card、Steps、Tabs 等多种文档专用组件，由 Nuxt UI 提供支持。 ::: :::u-page-feature --- icon: i-lucide-search --- #title 全文搜索 #description 基于 Nuxt Content 的 `ContentSearch` 组件，支持键盘快捷键（⌘K）快速搜索文档内容。 ::: :: ::u-page-section --- class: dark:bg-neutral-950 --- #title AI 增强体验 #links :::u-button --- color: neutral size: lg to: https://docs.mhaibaraai.cn/docs/getting-started/ai-chat trailingIcon: i-lucide-arrow-right variant: subtle --- 了解 AI 功能 ::: #features :::u-page-feature --- icon: i-lucide-bot --- #title AI 聊天助手 #description 内置智能文档助手，基于 Vercel AI SDK 支持多种 LLM 模型（Mistral、Qwen、OpenRouter），实时解答文档相关问题。 ::: :::u-page-feature --- icon: i-lucide-plug --- #title MCP Server 支持 #description 集成 Model Context Protocol 服务器，为 AI 助手提供结构化的文档访问能力，提升对话准确性。 ::: :::u-page-feature --- icon: i-lucide-sparkles --- #title LLM 优化 #description 通过 `nuxt-llms` 模块自动生成 `llms.txt` 和 `llms-full.txt`，为 AI 工具提供优化的文档索引。 ::: :::u-page-feature --- icon: i-lucide-zap --- #title 流式响应 #description 支持 AI 响应流式输出和代码高亮，配合 `shiki-stream` 实现实时语法高亮渲染。 ::: :::u-page-feature --- icon: i-lucide-wrench --- #title 工具调用支持 #description AI 助手可调用内置工具函数进行文档搜索、组件查询等操作，提供更精准的答案。 ::: :::u-page-feature --- icon: i-lucide-settings --- #title 灵活的模型配置 #description 支持自定义 AI 模型列表、API 端点和参数，轻松切换不同的 LLM 服务提供商。 ::: :: # 简介 ## 什么是 Movk Nuxt Docs? Movk Nuxt Docs 是一个基于 [UI 文档模板](https://docs-template.nuxt.dev/){rel=""nofollow""} 的 Nuxt Layer，提供完整的文档站点功能。通过 [Nuxt Content](https://content.nuxt.com){rel=""nofollow""} 支持 Markdown 和 [MDC 语法](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""}，专注于内容创作。 我们在所有 Nuxt 模块文档中均采用了此主题，包括： ::card-group :::card --- icon: i-lucide-notebook target: _blank title: mhaibaraai.cn to: https://mhaibaraai.cn --- 技术博客和知识库站点 ::: :::card --- icon: i-lucide-package target: _blank title: "@movk/core" to: https://core.mhaibaraai.cn --- Vue.js 实用工具和 Composables 库 ::: :::card --- icon: i-lucide-shapes target: _blank title: "@movk/nuxt" to: https://nuxt.mhaibaraai.cn --- Nuxt 4 模块化工程套件，提供 Schema 驱动表单、UI 组件和工具函数 ::: :: ## 主要特性 - 基于 [Nuxt 4](https://nuxt.com){rel=""nofollow""} 和 [Nuxt UI](https://ui.nuxt.com){rel=""nofollow""} - 支持 [MDC 语法](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""}（Markdown + Vue 组件） - 组件文档自动生成（Props、Slots、Emits、示例） - Git 集成（提交历史、编辑链接） - 自动侧边栏导航和全文搜索 - 暗黑模式支持 - 响应式设计（移动优先） - SEO 优化和 OG 图片生成 - 完整 TypeScript 类型支持 - AI 功能集成（LLMs.txt、MCP Server、AI Chat） # 安装 ## 快速入门 选择合适的安装方式： ### 完整文档站点（推荐） 包含 ESLint、TypeScript 检查等开发工具的完整模板。 ```bash [Terminal] npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs cd my-docs pnpm dev ``` ### 模块文档站点（精简） 精简模板，适合 npm 包文档，内置 Release 页面。 ```bash [Terminal] npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/module my-module-docs cd my-module-docs pnpm dev ``` 启动后访问 {rel=""nofollow""}。 ## 作为 Layer 使用 在现有 Nuxt 项目中集成： ```bash [Terminal] pnpm add @movk/nuxt-docs better-sqlite3 ``` 导入样式： ```css [app/assets/css/main.css] @import 'tailwindcss'; @import '@nuxt/ui'; ``` 配置 Nuxt： ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@movk/nuxt-docs'], css: ['~/assets/css/main.css'], llms: { domain: 'https://docs.mhaibaraai.cn', title: 'Movk Nuxt Docs', description: '一款优雅的 Nuxt 文档主题' } }) ``` # 项目结构 ## 整体结构 Movk Nuxt Docs 是一个 Nuxt Layer，扩展标准 Nuxt 应用为文档站点。 使用 `npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs` 创建项目后的结构： ```bash my-docs/ ├── app/ │ ├── assets/css/main.css # 全局样式 │ └── composables/ # 自定义 Composables ├── content/ # Markdown 内容 │ ├── index.md # 首页 │ └── docs/ # 文档页面 ├── public/ # 静态资源 ├── nuxt.config.ts # Nuxt 配置 ├── tsconfig.json # TypeScript 配置 ├── package.json # 依赖与脚本 ├── pnpm-workspace.yaml # pnpm 工作区配置 └── README.md # 项目说明 ``` ### 内容目录 `content/` Markdown 文档存放位置，自动生成路由。 ```bash content/ ├── index.md └── docs/ ├── 1.index.md └── 2.installation.md ``` ### 公共资源目录 `public/` 静态资源目录，文件直接在根路径提供服务，不经过构建处理。存放图片、图标等资源。 ### 依赖管理 `package.json` 定义项目依赖和脚本。典型的 `package.json` 非常精简： ```json [package.json] { "name": "movk-nuxt-docs-template", "packageManager": "pnpm@10.18.3", "scripts": { "build": "nuxt build", "dev": "nuxt dev" }, "dependencies": { "@movk/nuxt-docs": "latest", "better-sqlite3": "^12.5.0", "nuxt": "^4.2.2" } } ``` ### 样式文件 `app/assets/css/main.css` ```css [app/assets/css/main.css] @import 'tailwindcss'; @import '@nuxt/ui'; @theme static { --font-sans: 'Public Sans', sans-serif; --container-8xl: 90rem; } :root { --ui-container: var(--container-8xl); } ``` ### Nuxt 配置文件 `nuxt.config.ts` ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@movk/nuxt-docs'], css: ['~/assets/css/main.css'], aiChat: { model: 'mistral/devstral-2', models: ['mistral/devstral-2', 'openrouter/qwen/qwen3-4b:free'] }, mcp: { name: 'My Docs' } }) ``` ### 应用配置文件 `app.config.ts` ::note 此文件对于启动 Movk Nuxt Docs 应用并非必需。 :: 您可以在此文件中配置 Movk Nuxt Docs，以匹配您的品牌、处理 SEO、以及自定义链接和社交媒体信息。 # 配置 ## 应用配置 ::warning{to="https://nuxt.com/docs/4.x/directory-structure/app/app-config"} 覆盖 `app.config.ts` 需要同时创建 `nuxt.config.ts` 文件。 :: ### Vercel Analytics 在 `app.config.ts` 中启用 Vercel Analytics： ```ts [app.config.ts] export default defineAppConfig({ vercelAnalytics: { enable: true, debug: false }, }) ``` ### SEO #### 全局配置 在 `app.config.ts` 中定义默认 SEO 元数据。 `site.name` 可在 `nuxt.config.ts` 中配置，默认值来自 `package.json` 的 `name` 字段。 ::code-group ```ts [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{to="https://content.nuxt.com/docs/collections/types#page-type"} 查看 Nuxt Content Front-Matter 文档。 :: ### 头部 (Header) ```ts [app.config.ts] export default defineAppConfig({ header: { title: '', // 标题 avatar: '', // 头像链接 to: '/', // 标题链接 search: true, // 显示搜索栏 colorMode: true, // 显示颜色模式切换器 links: ButtonProps[], // 头部链接按钮 }, }) ``` ### 页脚 (Footer) ```ts [app.config.ts] export default defineAppConfig({ footer: { // 版权信息 credits: `Copyright © 2024 - ${new Date().getFullYear()} YiXuan - MIT License`, // 页脚社交媒体图标链接 socials: [ { icon: 'i-lucide-brain', to: 'https://docs.mhaibaraai.cn/llms.txt', target: '_blank', label: 'Open LLMs', }, ], }, }) ``` ### 目录 (TOC) 您可以自定义每个页面右侧的内容目录（Table of Contents）。 ```ts [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](https://github.com/IonicaBizau/git-url-parse){rel=""nofollow""} 自动获取仓库信息，提供以下功能： - 头部和页脚的 GitHub 图标链接 - 目录底部的「在 GitHub 上编辑」和「报告问题」链接 - `CommitChangelog` 组件的提交历史 ### 基础配置 在 `app.config.ts` 中配置 GitHub 集成： ```ts [app.config.ts] export default defineAppConfig({ github: { branch: 'main', rootDir: 'docs', }, }) ``` **完整配置属性：** | 属性 | 类型 | 默认值 | 描述 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------- | | `owner` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | 自动检测 | 仓库所有者用户名 | | `name` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | 自动检测 | 仓库名称 | | `url` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | 自动检测 | 仓库完整 URL | | `branch` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | 自动检测 | Git 分支名称 | | `rootDir` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | - | 文档根目录路径 | | `commitPath` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `'src'` | 组件文件所在的基础路径 | | `suffix` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `'vue'` | 组件文件的默认扩展名 | | `casing` | `'auto' | 'kebab' | 'camel' | 'pascal'`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `'auto'` vue 文件用 PascalCase，其他用 camelCase | 文件命名格式 | | `since` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `'2025-01-31T04:00:00Z'` | 提交历史的起始时间(ISO 8601 格式) | | `until` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | 当前时间 | 提交历史的截止时间(ISO 8601 格式) | | `per_page` | `number`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `100` | 每次请求获取的提交数量 (1-100) | | `author` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | - | 按作者过滤提交记录，可使用 GitHub 用户名或邮箱 | | `dateFormat` | `object`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `{ locale: 'zh-CN', options: {...} }` | 日期格式化配置 | ::tip{to="https://docs.mhaibaraai.cn/docs/components/commit-changelog"} `commitPath` 、 `suffix` 、 `casing` 、 `since` 、 `until` 、 `per_page` 、 `author` 用于 `CommitChangelog` 组件。 `dateFormat` 用于 `PageLastCommit` 组件。查看 CommitChangelog 文档了解详情。 :: ### 禁用 GitHub 集成 设置 `github: false` 禁用 GitHub 集成： ```ts [app.config.ts] export default defineAppConfig({ github: false, }) ``` # 自定义 ::tip 在 `components/` 目录下创建同名 Vue 文件即可覆盖组件。 :: ## 头部 (Header) 页面顶部的完整导航系统，由多个子组件组成。 ### `Header` 主容器组件，整合所有头部子组件，包括 Logo、导航菜单、搜索、主题选择器等功能。 可通过创建 `components/header/Header.vue` 完全自定义整个头部结构。 ### `HeaderLogo` 显示站点 Logo 和名称，支持链接跳转。 ![HeaderLogo](https://docs.mhaibaraai.cn/components/HeaderLogo.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/header/HeaderLogo.vue variant: link --- 默认组件代码 :: ### `HeaderCenter` 桌面端导航菜单，使用 `UNavigationMenu` 组件渲染配置的导航链接。 ![HeaderCenter](https://docs.mhaibaraai.cn/components/HeaderCenter.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/header/HeaderCenter.vue variant: link --- 默认组件代码 :: 可通过 `useHeader()` 组合式函数的 `desktopLinks` 自定义菜单内容。 ### `HeaderBody` 移动端导航内容，包含响应式导航菜单和文档目录导航。 ::div{.flex.justify-center.bg-muted.py-5} :nuxt-img{alt="HeaderBody" height="400" src="https://docs.mhaibaraai.cn/components/HeaderBody.png"} :: ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/header/HeaderBody.vue variant: link --- 默认组件代码 :: ### `HeaderBottom` 文档页面专用的二级导航，以标签页形式显示主要文档分类。 ![HeaderBottom](https://docs.mhaibaraai.cn/components/HeaderBottom.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/header/HeaderBottom.vue variant: link --- 默认组件代码 :: 仅在访问 `/docs/` 路径时显示。 ### `HeaderCTA` 头部右侧的行动号召区域，默认在首页显示"Get Started"按钮，其他页面显示 AI 聊天入口。 ![HeaderCTA](https://docs.mhaibaraai.cn/components/HeaderCTA.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/header/HeaderCTA.vue variant: link --- 默认组件代码 :: ## 页面组件 ### `PageHeaderLinks` 文档页面标题右侧的操作菜单，默认提供复制页面、复制链接、查看源码、AI 对话、MCP 服务器等功能。 ![PageHeaderLinks](https://docs.mhaibaraai.cn/components/PageHeaderLinks.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/PageHeaderLinks.vue variant: link --- 默认组件代码 :: ### `DocsAsideLeftTop` 文档页面左侧边栏顶部插槽，默认为空占位组件。 ![DocsAsideLeftTop](https://docs.mhaibaraai.cn/components/DocsAsideLeftTop.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/DocsAsideLeftTop.vue variant: link --- 默认组件代码 :: 创建 `components/DocsAsideLeftTop.vue` 即可在左侧导航上方显示自定义内容。 ### `DocsAsideLeftBody` 文档页面左侧边栏主体内容插槽，默认为空占位组件。 ![DocsAsideLeftBody](https://docs.mhaibaraai.cn/components/DocsAsideLeftBody.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/DocsAsideLeftBody.vue variant: link --- 默认组件代码 :: 创建 `components/DocsAsideLeftBody.vue` 即可在左侧导航主体区域显示自定义内容。 ### `DocsAsideRightBottom` 文档页面右侧边栏底部插槽，默认为空占位组件。 ![DocsAsideRightBottom](https://docs.mhaibaraai.cn/components/DocsAsideRightBottom.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/DocsAsideRightBottom.vue variant: link --- 默认组件代码 :: 创建 `components/DocsAsideRightBottom.vue` 即可在右侧目录下方显示自定义内容。 ## 页脚 (Footer) 页面底部布局组件。 ### `Footer` 主容器组件，整合页脚左右两侧内容，包含分隔线和布局样式。 ![Footer](https://docs.mhaibaraai.cn/components/Footer.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/footer/Footer.vue variant: link --- 默认组件代码 :: ### `FooterLeft` 页脚左侧区域，通过 `app.config.ts` 中的 `footer.credits` 配置显示版权信息。 ![FooterLeft](https://docs.mhaibaraai.cn/components/FooterLeft.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/footer/FooterLeft.vue variant: link --- 默认组件代码 :: ### `FooterRight` 页脚右侧区域，通过 `app.config.ts` 中的 `footer.socials` 配置显示社交媒体链接按钮。 ![FooterRight](https://docs.mhaibaraai.cn/components/FooterRight.png) ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/footer/FooterRight.vue variant: link --- 默认组件代码 :: ## 主题选择器 (ThemePicker) ### `ThemePicker` 主题自定义工具，提供可视化界面调整： - **Primary**：主色调（支持设置为黑色或预设颜色） - **Neutral**：中性色 - **Radius**：圆角大小（0-3） - **Font**：字体选择 - **Icons**：图标集选择 - **Color Mode**：颜色模式（亮色/暗色/系统） 修改后可导出 CSS 变量或 `app.config.ts` 配置。 ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/theme-picker/ThemePicker.vue variant: link --- 默认组件代码 :: ### `ThemePickerButton` 主题选择器内部使用的按钮组件，用于颜色、圆角等选项的选择。 ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/theme-picker/ThemePickerButton.vue variant: link --- 默认组件代码 :: # Nuxt ## Vue 页面 Movk Nuxt Docs 提供了三个内置页面： - `pages/index.vue`：首页 - `pages/releases.vue`：发布日志页面 - `pages/docs/[...slug].vue`：文档页面 您可以通过在 `app/pages/` 目录下创建 Vue 文件来添加自定义页面。例如，创建一个简单的 `hello.vue` 页面： ```vue [app/pages/hello.vue] ``` ## 扩展页面 ::tip --- to: https://content.nuxt.com/docs/collections/inherit-schema-from-component --- 从 Vue 组件继承 Schema :: 您可以通过以下配置定义一个 `releases` 页面： ::code-tree{default-value="content.config.ts"} ```ts [content.config.ts] import { defineCollection, defineContentConfig, z, property } from '@nuxt/content' import { asSeoCollection } from '@nuxtjs/seo/content' export default defineContentConfig({ collections: { releases: defineCollection(asSeoCollection({ type: 'page', source: 'releases.yml', schema: z.object({ releases: z.string(), hero: property(z.object({})).inherit('@nuxt/ui/components/PageHero.vue') }) })) } }) ``` ```vue [app/pages/releases.vue] ``` ```mdc [content/releases.yaml] title: 发布日志 description: 了解 Movk Nuxt Docs 的最新功能、改进和错误修复。 navigation: false hero: title: 发布日志 description: 了解 Movk Nuxt Docs 的最新功能、改进和错误修复。 releases: https://ungh.cc/repos/mhaibaraai/movk-nuxt-docs/releases links: - label: 在 GitHub 上标星 color: neutral variant: outline to: https://github.com/mhaibaraai/movk-nuxt-docs target: _blank icon: i-lucide-star ``` :: ## 布局 Movk Nuxt Docs 提供了两个内置布局： - `default` 布局：用于首页和自定义 Vue 页面 - `docs` 布局：用于文档页面 ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/layouts/docs.vue variant: link --- 默认布局代码 :: 如果您想使用不同的布局，可以在 `app/layouts/` 目录下创建。 ```vue [app/layouts/custom.vue] ``` # 部署 ## 构建生产版本 ```bash pnpm build ``` 构建产物位于 `.output/` 目录，包含服务端和客户端代码。 ## Vercel 部署 ### 自动部署 1. 在 Vercel 创建新项目 2. 连接 Git 仓库 3. 配置环境变量： ```bash GITHUB_TOKEN=your-token AI_GATEWAY_API_KEY=your-key OPENROUTER_API_KEY=your-key ``` 4. 部署命令默认为 `nuxt build` ## 环境变量 | 变量 | 用途 | 必需场景 | | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | | `GITHUB_TOKEN`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | Git 集成 | 显示提交历史 | | `AI_GATEWAY_API_KEY`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | AI Chat 功能 | 使用 AI Chat | | `OPENROUTER_API_KEY`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | AI Chat 功能 | 使用 AI Chat | ## 相关资源 - [Nuxt 部署文档](https://nuxt.com/deploy){rel=""nofollow""} - [Nitro 部署指南](https://nitro.unjs.io/deploy){rel=""nofollow""} # AI Chat ## 概述 一个提供基于 MCP（模型上下文协议）工具的 AI 聊天界面的 Nuxt 模块。 **主要功能：** - 支持多种 AI 模型（通过 **AI SDK Gateway** 或 **OpenRouter**） - 带有流式响应的 AI 聊天侧滑组件 - 用于快速提问的浮动输入组件 - MCP 工具调用（文档检索） - 代码高亮和 Markdown 渲染 - 思考过程展示（Extended Thinking） - 持久化聊天状态 - 支持键盘快捷键 - 支持可用模型列表选取 ::div{.flex.justify-center.bg-muted.py-5} :nuxt-img{alt="AiChat" height="600" src="https://docs.mhaibaraai.cn/ai/AiChat.png"} :: ## 快速开始 Movk Nuxt Docs 已内置 AI Chat 模块。要启用该模块，请在 `nuxt.config.ts` 中进行配置： ::steps ### 在 `nuxt.config.ts` 中添加模块： ```ts [nuxt.config.ts] export default defineNuxtConfig({ aiChat: { apiPath: '/api/ai-chat', mcpPath: '/mcp', model: 'openai/gpt-5-nano', models: [ 'openai/gpt-5-nano', 'anthropic/claude-haiku-4.5', 'google/gemini-2.5-flash', 'openrouter/anthropic/claude-haiku-4.5', 'openrouter/openai/gpt-5-nano', ], } }) ``` 模块配置选项： | 选项 | 类型 | 默认值 | 描述 | | --------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------- | -------------------------------------- | | `apiPath` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `/api/ai-chat` | 聊天 API 端点路径 | | `mcpPath` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `/mcp` | MCP 服务器连接路径 | | `model` | `string`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `-` | AI SDK Gateway、OpenRouter 的模型标识符 | | `models` | `string[]`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `[]` | 可用模型列表（格式为 "provider/model" 或 "model"） | ### 将您的 API 密钥设置为环境变量： ```bash [.env] # Using AI SDK Gateway AI_GATEWAY_API_KEY=your-gateway-key # Or using OpenRouter directly OPENROUTER_API_KEY=your-openrouter-key ``` :::warning 仅当检测到以下 API 密钥之一时，该模块才会启用。如果未找到密钥，模块将被禁用，并在控制台中记录一条消息。 ::: :: ## 手动安装 您可以选择手动安装该模块： - 将 `modules/ai-chat` 文件夹复制到你的 Nuxt 项目中 - 安装所需依赖： ```bash pnpm add @ai-sdk/mcp @ai-sdk/vue @ai-sdk/gateway @openrouter/ai-sdk-provider ai motion-v shiki shiki-stream ``` ## 使用方法 将组件添加到你的应用中： ```vue ``` ### Floating Input 使用 `AiChatFloatingInput` 在页面底部显示一个浮动输入框。 ::tip 使用 `Teleport` 将浮动输入渲染到 body 级别，确保它无论在组件层次结构中如何变化都能固定在底部 :: ```vue ``` ### 编程式控制 使用 `useAIChat` 组合式函数来控制聊天： ```vue ``` ## 组件 API ### AiChat 最简单的集成方式，展示助手按钮。 :component-props{slug="AiChat"} ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChat.vue variant: link --- 查看源代码 :: ### AiChatFloatingInput 浮动输入框，位于视口下方。无需任何属性。 **键盘快捷键：** - `⌘I` / `Ctrl+I` - 聚焦输入框 - `Escape` - 失焦输入框 - `Enter` - 提交问题 ::note 需使用 `Teleport` 和 `ClientOnly` 包裹以确保正确渲染。 :: ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatFloatingInput.vue variant: link --- 查看源代码 :: ### AiChatToolCall 在聊天中显示 MCP 工具调用。 :component-props{slug="AiChatToolCall"} ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatToolCall.vue variant: link --- 查看源代码 :: ### AiChatModelSelect 模型选择下拉菜单，用于切换 AI 模型。无需任何属性。 ::note 该组件会自动显示 `nuxt.config.ts` 中配置的 `models` 列表，并使用 `useModels` 组合式函数管理模型状态。 :: ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatModelSelect.vue variant: link --- 查看源代码 :: ### AiChatReasoning 显示 AI 思考过程的可折叠组件。 :component-props{slug="AiChatReasoning"} ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatReasoning.vue variant: link --- 查看源代码 :: ### AiChatSlideoverFaq 显示聊天为空时的常见问题分类。 ::tip{to="https://docs.mhaibaraai.cn/docs/composables/use-faq"} 您可以通过创建 `composables/useFaq.ts` 文件来覆盖默认的问题列表。 :: :component-props{slug="AiChatSlideoverFaq"} ```ts interface FaqCategory { category: string items: string[] } ``` ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatSlideoverFaq.vue variant: link --- 查看源代码 :: ### AiChatSlideover 完整的侧边栏对话界面。 :component-props{slug="AiChatSlideover"} ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatSlideover.vue variant: link --- 查看源代码 :: ### AiChatPreStream 用于流式渲染代码块的组件，集成 Shiki 语法高亮。 ::note **特性：** - 自动根据颜色模式切换主题（亮色/暗色） - 支持语言别名映射（如 'javascript' → 'js'） - 自动清理代码格式（去除尾随反引号） - 集成 `ProsePre` 组件样式 :: :component-props{slug="AiChatPreStream"} ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatPreStream.vue variant: link --- 查看源代码 :: ## Composables ### `useAIChat()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 对话状态管理，提供聊天界面的状态控制和消息管理功能。 #### 返回值 ::field-group :::field{name="isOpen" type="Ref"} 对话框是否打开的响应式状态。 ::: :::field{name="messages" type="Ref"} 消息列表，包含所有历史对话记录。 ::: :::field{name="pendingMessage" type="Ref"} 待发送的消息内容，用于在打开对话框前预设问题。 ::: :::field{name="open" type="(message?: string, clearHistory?: boolean) => void"} 打开对话框并可选地发送初始消息。 ::::collapsible :::::field-group ::::::field{name="message" type="string"} 可选的初始消息，打开对话框时自动发送。 :::::: ::::::field{name="clearHistory" type="boolean"} 是否清除之前的消息历史，默认为 `false` 。 :::::: ::::: :::: ::: :::field{name="close" type="() => void"} 关闭对话框。 ::: :::field{name="toggle" type="() => void"} 切换对话框的打开/关闭状态。 ::: :::field{name="clearMessages" type="() => void"} 清除所有历史消息。 ::: :::field{name="clearPending" type="() => void"} 清除待发送的消息。 ::: :: ### `useModels()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 模型配置管理，控制可用的 AI 模型列表和当前选中的模型。 #### 返回值 ::field-group :::field{name="models" type="Ref"} 可用模型列表，从 `nuxt.config.ts` 的 `aiChat.models` 配置读取。 ::: :::field{name="model" type="Ref"} 当前选中的模型 ID，会持久化到 localStorage。 ::: :::field{name="formatModelName" type="(modelId: string) => string"} 格式化模型 ID 为易读的显示名称（去除前缀和后缀）。 ::::collapsible :::::field-group ::::::field --- required: true name: modelId type: string --- 模型 ID，格式如 `openrouter/mistralai/devstral-2512:free` 。 :::::: ::::: :::: ::: :: ### `useTools()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 工具和模型获取，提供 MCP 工具标签生成和模型实例化功能。 #### 返回值 ::field-group :::field{name="getToolLabel" type="(toolName: string, args?: any) => string"} 根据工具名称和参数生成用户友好的显示标签。 ::::collapsible :::::field-group ::::::field --- required: true name: toolName type: string --- MCP 工具名称。 :::::: ::::::field{name="args" type="any"} 工具调用的参数对象。 :::::: ::::: :::: ::: :::field{name="getModel" type="(modelId: string) => LanguageModel"} 根据模型 ID 获取 AI SDK 的 `LanguageModel` 实例。 ::::collapsible :::::field-group ::::::field --- required: true name: modelId type: string --- 模型 ID，支持 AI Gateway 和 OpenRouter 格式。 :::::: ::::: :::: ::: :: ### `useHighlighter()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 异步加载 Shiki 代码高亮器实例，用于代码块的语法高亮渲染。 #### 返回值 返回一个 Promise，resolve 为配置好的 Shiki Highlighter 实例。 ::note **支持的语言：** `vue`, `js`, `ts`, `css`, `html`, `json`, `yaml`, `markdown`, `bash` **支持的主题：** - `material-theme-palenight`（深色模式） - `material-theme-lighter`（浅色模式） :: ```ts const highlighter = await useHighlighter() // 使用示例 const html = highlighter.codeToHtml(code, { lang: 'typescript', theme: 'material-theme-palenight' }) ``` ## 自定义 ### 系统提示词 要自定义 AI 的行为，请编辑以下文件中的系统提示词： `server/api/search.ts` ::u-button --- color: neutral icon: i-lucide-code-xml target: _blank to: https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/server/api/search.ts variant: link --- 默认系统提示词 :: ### 样式 组件使用 Nuxt UI 和 Tailwind CSS 设计令牌。你可以通过修改组件文件或覆盖 UI 属性来自定义外观。 ## 版本依赖 ```json [package.json] { "@ai-sdk/gateway": "^3.0.5", "@ai-sdk/mcp": "^1.0.2", "@ai-sdk/vue": "^3.0.6", "@openrouter/ai-sdk-provider": "^1.5.4", "ai": "^6.0.6", "motion-v": "^1.7.4", "shiki": "^3.20.0", "shiki-stream": "^0.1.2" } ``` # LLMs.txt ## 什么是 LLMs.txt？ 默认集成 `nuxt-llms`，为大型语言模型预处理文档内容。系统自动生成并预渲染 `/llms.txt` 和 `/llms-full.txt` 文件。 ::note{to="https://docs.mhaibaraai.cn/llms.txt"} 请查看为 Movk Nuxt Docs 文档本身生成的 `/llms.txt` 文件。 - `/llms.txt` - 包含所有内容的结构化概览及其文档链接（约 5K tokens） - `/llms-full.txt` - 提供完整文档，包括实现细节、示例、类型定义和最佳实践（100K+ tokens） :: ## 默认端点 以下是生成 `/llms.txt` 文件时使用的默认值： - `domain`： 根据您的部署平台计算得出（或通过使用 `NUXT_SITE_URL` 环境变量） - `title`：提取自您的 `package.json` 文件 - `description`：提取自您的 `package.json` 文件 - `full.title`：提取自您的 `package.json` 文件 - `full.description`：提取自您的 `package.json` 文件 ## 自定义 LLMs.txt 生成 您可以通过在 `nuxt.config.ts` 中配置 `llms` 选项来自定义 LLMs.txt 文件的生成： ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { domain: 'https://your-site.com', title: 'Your Site Name', description: 'A brief description of your site', full: { title: 'Your Site Name', description: 'A brief description of your site', }, }, }) ``` ## 选择正确的文件 ::note **大多数用户应该从 /llms.txt 开始** \- 它包含所有基本信息，适用于标准 LLM 上下文窗口。仅当您需要完整的实现示例且 AI 工具支持大型上下文（200K+ tokens）时，才使用 `/llms-full.txt` 。 :: ## 重要使用说明 ::warning **@ 符号必须手动输入** \- 使用 Cursor 或 Windsurf 等工具时，必须在聊天界面中手动输入 `@` 符号。复制粘贴会破坏工具识别它作为上下文引用的能力。 :: ## AI 工具使用方法 ### Cursor 您可以在 Cursor 中引用 LLMs.txt 文件，以获得更好的 AI 辅助。 #### 使用方法 1. **直接引用**：在提问时提及 LLMs.txt URL 2. 使用 `@docs` 将这些特定 URL 添加到项目上下文中 ::note{to="https://docs.cursor.com/en/context/@-symbols/@-docs"} 了解更多关于 Cursor Web 和文档搜索 :: ### Windsurf Windsurf 可以直接访问 LLMs.txt 文件以了解函数使用和最佳实践。 #### 在 Windsurf 中使用 LLMs.txt - 使用 `@docs` 引用特定的 LLMs.txt URL - 在工作区中创建引用这些 URL 的持久规则 ::note{to="https://docs.windsurf.com/windsurf/cascade/web-search"} 了解更多关于 Windsurf Web 和文档搜索 :: ### 其他 AI 工具 任何支持 LLMs.txt 的 AI 工具都可以使用这些端点来更好地理解您的文档。 #### ChatGPT、Claude 或其他 LLM 的示例 - "使用文档 {rel=""nofollow""}" - "遵循完整指南 {rel=""nofollow""}" # MCP Server ## 关于 MCP Server 每个 Movk Nuxt Docs 实例内置 Model Context Protocol (MCP) 服务器，任何 MCP 客户端（Claude、Cursor、VS Code 等）均可连接。 ::note **什么是 MCP？** Model Context Protocol 是开放协议，支持 AI 应用与外部服务的标准化连接。通过 MCP，AI 助手可根据上下文主动搜索文档。 :: 当连接到 AI 工具时，LLM 能够根据对话上下文智能地判断何时需要访问文档工具，从而在开发过程中为您提供更准确的文档引用和技术支持。 ## 访问您的 MCP 服务器 您的 MCP 服务器可通过文档网址的 `/mcp` 路径自动访问。 ::tip 例如，如果您的文档托管在 `https://docs.example.com` ，则您的 MCP 服务器 URL 为 `https://docs.example.com/mcp` 。 :: ## 配置选项 ### 禁用 MCP 服务器 在 `nuxt.config.ts` 中禁用 MCP 服务器： ```ts [nuxt.config.ts] export default defineNuxtConfig({ mcp: { enabled: false } }) ``` ### 自定义服务器名称 ```ts [nuxt.config.ts] export default defineNuxtConfig({ mcp: { name: 'My Docs' } }) ``` ## 内置工具 MOVK Docs MCP 提供两个开箱即用的工具： ### `list-pages` 列出所有可用的文档页面及分类信息。 **使用场景：** - 搜索某个主题的文档但不知道确切路径 - 了解整体文档结构 - 查找特定类别的所有页面 ### `get-page` 检索特定文档页面的完整内容。 **参数：** - `path` *（必需）* - 页面路径，例如 `/docs/getting-started/installation` **使用场景：** - 获取确切路径页面的完整内容 - 引用特定页面的详细信息 - 获取完整 Markdown 源代码 ## 设置指南 MCP 服务器采用 HTTP 传输协议，可安装于不同 AI 助手中。 ### Claude Code ::note **确保已安装 Claude Code** \- 访问 [Anthropic 文档](https://docs.anthropic.com/en/docs/claude-code/quickstart){rel=""nofollow""} 获取安装说明。 :: 使用 CLI 命令添加服务器： ```bash claude mcp add --transport http my-docs https://docs.example.com/mcp ``` ### Claude Desktop 1. 打开 Claude Desktop，前往「Settings」>「Developer」 2. 点击「Edit Config」，这将打开本地 Claude 目录 3. 使用自定义 MCP 服务器配置修改 `claude_desktop_config.json` 文件： ```json [claude_desktop_config.json] { "mcpServers": { "my-docs": { "command": "npx", "args": [ "mcp-remote", "https://docs.example.com/mcp" ] } } } ``` 4. 重启 Claude Desktop 应用 ### Cursor :install-button{url="https://docs.example.com/mcp"} 或者在项目根目录创建或更新 `.cursor/mcp.json`： ```json [.cursor/mcp.json] { "mcpServers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Visual Studio Code ::note **安装所需扩展** \- 确保已安装 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot){rel=""nofollow""} 和 [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat){rel=""nofollow""} 扩展。 :: :install-button{ide="vscode" url="https://docs.example.com/mcp"} 或者在项目的 `.vscode` 文件夹中创建或编辑 `mcp.json` 文件： ```json [.vscode/mcp.json] { "servers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### ChatGPT ::note **使用 MCP 的自定义连接器在 Web 上的 ChatGPT Pro 和 Plus 账户可用** 。 :: 1. **启用开发者模式**：前往设置 → Connectors → Advanced settings → Developer mode 2. **打开 ChatGPT 设置** 3. **在 Connectors 选项卡中，创建新连接器**： - 名称：`My Docs` - MCP server URL：`https://docs.example.com/mcp` - 认证：`None` 4. **点击创建** My Docs 连接器将在对话期间出现在撰写器的「开发者模式」工具中。 ### Opencode 在项目根目录创建 `opencode.json`： ```json [opencode.json] { "$schema": "https://opencode.ai/config.json", "mcp": { "my-docs": { "type": "remote", "url": "https://docs.example.com/mcp", "enabled": true } } } ``` ## 使用示例 配置完成后，您可以向 AI 助手提出如下问题，它们将自动使用 MCP 服务器查询文档： - 「列出所有可用的文档页面」 - 「获取入门指南的内容」 - 「查找关于组件的文档」 - 「显示配置相关的文档页面」 - 「获取 /docs/getting-started/installation 页面的完整内容」 - 「有哪些关于主题定制的文档？」 - 「展示所有 API 参考文档」 - 「我需要了解如何部署项目，有相关文档吗？」 AI 助手将在生成响应时主动搜索文档，根据对话上下文智能判断何时需要查询工具，为您提供准确的文档引用和技术支持。 ## 自定义扩展 您可以通过创建自定义组件来扩展 MCP 服务器的功能。 ### 自定义工具 在 `server/mcp/tools/` 目录中创建自定义工具文件： ```ts [server/mcp/tools/my-tool.ts] import { z } from 'zod/v4' export default defineMcpTool({ description: '工具的详细描述，帮助 AI 理解何时使用此工具', inputSchema: { param: z.string().describe('参数说明') }, cache: '1h', // 可选：设置缓存时间 handler: async ({ param }) => { // 工具逻辑 return { content: [{ type: 'text', text: '返回内容' }] } } }) ``` ### 自定义资源 在 `server/mcp/resources/` 目录中创建可被发现的资源： ```ts [server/mcp/resources/changelog.ts] export default defineMcpResource({ file: 'CHANGELOG.md', metadata: { description: '项目的变更日志', }, }) ``` 这会自动处理 URI 生成、MIME 类型检测和文件读取。 ### 自定义提示 在 `server/mcp/prompts/` 目录中创建可重用的提示： ```ts [server/mcp/prompts/greeting.ts] export default defineMcpPrompt({ name: 'greeting', title: '问候', description: '生成个性化问候消息', handler: async () => { const hour = new Date().getHours() const timeOfDay = hour < 12 ? '早上' : hour < 18 ? '下午' : '晚上' return { messages: [{ role: 'user', content: { type: 'text', text: `${timeOfDay}好！有什么可以帮您的吗？`, }, }], } }, }) ``` ### 添加自定义处理程序 可以在 `server/mcp/` 目录下创建自定义处理器： ```ts [server/mcp/migration.ts] import { z } from 'zod/v4' const migrationTool = defineMcpTool({ name: 'migrate-v3-to-v4', title: '将 v3 迁移到 v4', description: '将代码从版本 3 迁移到版本 4', inputSchema: { code: z.string().describe('要迁移的代码'), }, handler: async ({ code }) => { const migrated = code.replace(/v3/g, 'v4') return { content: [{ type: 'text', text: migrated, }], } }, }) export default defineMcpHandler({ name: 'migration', version: '0.1.0', route: '/mcp/migration', tools: [migrationTool], browserRedirect: '/', }) ``` ### 覆盖默认工具 要覆盖内置的 `list-pages` 或 `get-page` 工具，只需在 `server/mcp/tools/` 目录中创建同名文件即可。 ```ts [server/mcp/tools/list-pages.ts] import { z } from 'zod/v4' export default defineMcpTool({ description: '自定义列表页实现', inputSchema: { locale: z.string().optional(), category: z.string().optional(), }, handler: async ({ locale, category }) => { const pages = await getCustomPageList(locale, category) return { content: [{ type: 'text', text: JSON.stringify(pages) }], } }, }) ``` ::tip{to="https://mcp-toolkit.nuxt.dev/"} 有关工具、资源、提示、处理程序和高级配置的更多信息，请查阅 Nuxt MCP Toolkit 工具包文档。 :: # Markdown 语法 ## 标题 使用标题来组织文档的主要部分，这有助于用户更好地导航和理解内容。 ::code-preview --- class: "[&>div]:*:my-0" --- ## 标题 #code ```mdc ## 标题 ``` :: ### 副标题 使用副标题进一步细分内容，创建更清晰的层次结构，提高可读性。 ::code-preview --- class: "[&>div]:*:my-0" --- ### 副标题 #code ```mdc ### 副标题 ``` :: ::tip 每个标题和副标题都会自动生成一个锚点，并显示在页面的目录中。 :: ## 文本格式化 Movk Nuxt Docs 支持大多数标准的 Markdown 文本格式化选项。 | 样式 | 语法 | 效果 | | --- | --------- | ------- | | 粗体 | `**粗体**` | **粗体** | | 斜体 | `*斜体*` | *斜体* | | 删除线 | `~~删除线~~` | ~~删除线~~ | 您可以组合使用这些格式，以实现更丰富的文本样式和视觉强调。 | 样式 | 语法 | 效果 | | ----- | ------------ | ---------- | | 粗斜体 | `***粗斜体***` | ***粗斜体*** | | 粗体删除线 | `~~**粗体**~~` | ~~**粗体**~~ | | 斜体删除线 | `~~*斜体*~~` | ~~*斜体*~~ | ## 链接 链接用于连接文档的不同部分或指向外部资源，对于用户导航和提供参考至关重要。要创建链接，请将链接文本包裹在方括号 `[]` 中，后跟圆括号 `()` 内的 URL。 ::code-preview --- class: "[&>div]:*:my-0" --- [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt){rel=""nofollow""} #code ```mdc [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt) ``` :: ### 内部链接 要在文档内部创建链接，请使用相对于根目录的路径，例如 `/docs/guide/installation`。 ::code-preview --- class: "[&>div]:*:my-0" --- [安装](https://docs.mhaibaraai.cn/docs/guide/installation) #code ```mdc [安装](/docs/guide/installation) ``` :: ## 列表 列表以结构化、易于阅读的格式组织相关项目。Markdown 支持无序列表、有序列表和嵌套列表，以满足不同的内容需求。 ### 无序列表 对于没有特定顺序的项目，请使用无序列表。每个列表项以 `-` 符号开头。 ::code-preview --- class: "[&>div]:*:my-0" --- - 我是列表项目。 - 我是另一个列表项目。 - 我是最后一个列表项目。 #code ```mdc - 我是列表项目。 - 我是另一个列表项目。 - 我是最后一个列表项目。 ``` :: ### 有序列表 当项目顺序重要时使用有序列表，如流程中的步骤。每项以数字开头。 ::code-preview --- class: "[&>div]:*:my-0" --- 1. 我是列表项目。 2. 我是另一个列表项目。 3. 我是最后一个列表项目。 #code ```mdc 1. 我是列表项目。 2. 我是另一个列表项目。 3. 我是最后一个列表项目。 ``` :: ### 嵌套列表 为复杂结构创建具有子项目的分层列表。通过四个空格缩进子项目以进行嵌套。 ::code-preview --- class: "[&>div]:*:my-0" --- - 我是列表项目。 - 我是嵌套列表项目。 - 我是另一个嵌套列表项目。 - 我是另一个列表项目。 #code ```mdc - 我是列表项目。 - 我是嵌套列表项目。 - 我是另一个嵌套列表项目。 - 我是另一个列表项目。 ``` :: ## 表格 清晰地以行和列的形式呈现结构化数据。表格非常适合比较数据或列出属性。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- | Prop | Default | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | #code ```mdc | Prop | Default | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | ``` :: ## 块引用 突出显示重要的引用、参考或强调的文本。块引用在视觉上区分引用的内容。 ### 单行 单行块引用最适合短小、有力的引用或适合在一行内的引用。要创建单行块引用，在段落前添加 `>`。非常适合短小且有力的引用。 ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI 是一个建立在 Reka UI 之上的 Vue 组件、可组合函数和工具的集合，面向结构和布局，被设计为应用程序的构建块。 #code ```mdc > Nuxt UI 是一个建立在 Reka UI 之上的 Vue 组件、可组合函数和工具的集合，面向结构和布局，被设计为应用程序的构建块。 ``` :: ### 多行 多行块引用适用于较长的引用或当您需要在单个引用中包含多个段落时。 ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI 是一个建立在 Reka UI 之上的 Vue 组件、可组合函数和工具的集合，面向结构和布局，被设计为应用程序的构建块。 > > 使用 Nuxt UI 创建美观、响应式和可访问的 Vue 应用程序。 #code ```mdc > Nuxt UI 是一个建立在 Reka UI 之上的 Vue 组件、可组合函数和工具的集合，面向结构和布局，被设计为应用程序的构建块。 > > 使用 Nuxt UI 创建美观、响应式和可访问的 Vue 应用程序。 ``` :: # 代码块 ## 基础用法 ### 内联代码 使用反引号包裹内联代码，适合在句子中引用代码元素。 ::code-preview --- class: "[&>div]:*:my-0" --- `内联代码` #code ```mdc `内联代码` ``` :: ### 代码块 使用三个反引号展示带语法高亮的多行代码。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: 在编写代码块时，您可以指定一个文件名显示在代码块的顶部。图标会根据文件扩展名或名称自动匹配。这有助于用户理解代码在项目中的位置和用途。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: 每个代码块都内置了一个复制按钮，方便用户将代码复制到剪贴板。 ::tip{to="https://ui.nuxt.com/getting-started/icons/nuxt#theme"} 图标已默认定义，但您可以在 `app.config.ts` 中进行自定义： ```ts [app.config.ts] export default defineAppConfig({ ui: { prose: { codeIcon: { terminal: 'i-ph-terminal-window-duotone' } } } }) ``` :: ## 高级用法 ### 代码组 使用 `code-group` 组件在选项卡中对多个代码块进行分组，非常适合用于展示多种语言或包管理器的代码示例。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-group{.w-full} ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` ::: #code ````mdc :::code-group ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` :: ```` :: ### 代码树 使用 `code-tree` 在文件树视图中显示代码块。`code-tree` 非常适合展示项目结构和文件关系。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-tree{default-value="app/app.config.ts"} ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'], css: ['~/assets/css/main.css'] }) ``` ```css [app/assets/css/main.css] @import "tailwindcss"; @import "@nuxt/ui"; ``` ```ts [app/app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'sky', colors: 'slate' } } }) ``` ```vue [app/app.vue] ``` ```json [package.json] { "name": "nuxt-app", "private": true, "type": "module", "scripts": { "build": "nuxt build", "dev": "nuxt dev", "generate": "nuxt generate", "preview": "nuxt preview", "lint": "eslint .", "lint:fix": "eslint --fix ." }, "dependencies": { "@iconify-json/lucide": "^1.2.18", "@nuxt/ui": "^4.0.0", "nuxt": "^4.2.2" }, "devDependencies": { "eslint": "^9.34.0", "typescript": "^5.9.3", "vue-tsc": "^3.0.6" } } ``` ```json [tsconfig.json] { "extends": "./.nuxt/tsconfig.json" } ``` ````md [md\\] [README.md] # Nuxt 4 Minimal Starter Look at the [Nuxt 4 documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. ## Setup Make sure to install the dependencies: ```bash # npm npm install # pnpm pnpm install # yarn yarn install # bun bun install ``` ## Development Server Start the development server on `http://localhost:3000`: ```bash # npm npm run dev # pnpm pnpm run dev # yarn yarn dev # bun bun run dev ``` ## Production Build the application for production: ```bash # npm npm run build # pnpm pnpm run build # yarn yarn build # bun bun run build ``` Locally preview production build: ```bash # npm npm run preview # pnpm pnpm run preview # yarn yarn preview # bun bun run preview ``` Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. ```` ::: :: ### `CodePreview` 使用 `code-preview` 显示代码输出与代码并排。`code-preview` 非常适合交互式示例和演示代码结果。 在 `default` 插槽中编写要预览的代码，在 `code` 插槽中编写实际代码。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" label: 预览 --- :::code-preview --- class: "[&>div]:*:my-0" --- `内联代码` #code ```mdc `内联代码` ``` ::: #code ````mdc ::code-preview `内联代码` #code ```mdc `内联代码` ``` :: ```` :: ### `CodeCollapse` 使用 `code-collapse` 对于长代码块以保持页面整洁。`code-collapse` 允许用户仅在需要时展开代码块，提高可读性。 ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-collapse --- class: "[&>div]:my-0" --- ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` ::: #code ````mdc ::code-collapse ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` :: ```` :: # Markdown 组件 Prose 组件是标准 HTML 排版标签的替代品，在 Markdown 中提供自定义 UI。 **Movk Nuxt Docs** 和 **Nuxt UI** 提供设计精美的 Prose 组件，支持 [MDC 语法](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""}。 ::prose-note{to="https://ui.nuxt.com/getting-started"} 本页仅列举适合文档的 Prose 组件。所有 Nuxt UI 组件均可在 Markdown 中使用。完整组件列表请查看 [Nuxt UI 文档](https://ui.nuxt.com/getting-started){rel=""nofollow""} 。 :: ### `Accordion` 使用 `accordion` 和 `accordion-item` 组件在您的内容中嵌入一个 [Accordion](https://ui.nuxt.com/components/accordion){rel=""nofollow""}。 ::tabs :::tabs-item{icon="i-lucide-eye" label="Preview"} ::::accordion :::::accordion-item --- icon: i-lucide-circle-help label: 什么是 Movk Nuxt Docs，它的主要特性是什么？ --- Movk Nuxt Docs 是一个使用 Nuxt UI 构建的完全集成的文档解决方案。它是一个基于 UI 文档模板的主题，提供开箱即用的视觉效果。用户可以专注于使用 Markdown 和 MDC 语法编写内容。 ::::: :::::accordion-item{icon="i-lucide-circle-help" label="如何开始使用 Movk Nuxt Docs？"} 要开始一个 Movk Nuxt Docs 项目，您只需要一个 `content/` 文件夹。您可以查看入门模板以快速开始。 ::::: :::::accordion-item{icon="i-lucide-circle-help" label="什么是 Nuxt UI？"} [Nuxt UI](https://ui.nuxt.com/){rel=""nofollow""} 是一个包含高质量 Vue 组件、可组合项和工具的集合。 ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::accordion :::accordion-item{label="什么是 Movk Nuxt Docs，它的主要特性是什么？" icon="i-lucide-circle-help"} Movk Nuxt Docs 是一个使用 Nuxt UI 构建的完全集成的文档解决方案。它是一个基于 UI 文档模板的主题，提供开箱即用的视觉效果。用户可以专注于使用 Markdown 和 MDC 语法编写内容。 ::: :::accordion-item{label="如何开始使用 Movk Nuxt Docs？" icon="i-lucide-circle-help"} 要开始一个 Movk Nuxt Docs 项目，您只需要一个 `content/` 文件夹。您可以查看入门模板以快速开始。 ::: :::accordion-item{label="什么是 Nuxt UI？" icon="i-lucide-circle-help"} [Nuxt UI](https://ui.nuxt.com/) 是一个包含高质量 Vue 组件、可组合项和工具的集合。 ::: :: ``` ::: :: ### `Badge` 在 `badge` 组件的默认插槽中使用 Markdown，在您的内容中显示一个 [Badge](https://ui.nuxt.com/components/badge){rel=""nofollow""}。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::badge **v3.0.0** :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::badge **v3.0.0** :: ``` ::: :: ### `Callout` 在 `callout` 组件的默认插槽中使用 Markdown，为您的内容添加引人注目的上下文信息。 使用 `icon` 和 `color` 属性来自定义其外观。您还可以传递 [``](https://nuxt.com/docs/api/components/nuxt-link){rel=""nofollow""} 组件的任何属性。 此外，您可以使用具有预定义图标和颜色的 `note`、`tip`、`warning` 和 `caution` 快捷方式。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::div{.flex.flex-col.gap-4.w-full} :::::note{.w-full.my-0} 这是一些额外的信息。 ::::: :::::tip{.w-full.my-0} 这是一个有帮助的建议。 ::::: :::::warning{.w-full.my-0} 请小心此操作，因为它可能产生意外结果。 ::::: :::::caution{.w-full.my-0} 此操作无法撤销。 ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::note 这是一些额外信息。 :: ::tip 这是一个有帮助的建议。 :: ::warning 请小心此操作，因为它可能产生意外结果。 :: ::caution 此操作无法撤销。 :: ``` ::: :: ### `Card` 和 `CardGroup` 在 `card` 组件的默认插槽中使用 Markdown 来突出显示您的内容。 使用 `title`、`icon` 和 `color` 属性来自定义它。您还可以传递 [``](https://nuxt.com/docs/api/components/nuxt-link){rel=""nofollow""} 中的任何属性。 使用 `card-group` 组件包装您的 `card` 组件，将它们分组在一起以获得网格布局。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::card-group{.w-full.my-0} :::::card --- icon: i-simple-icons-github target: _blank title: Dashboard to: https://github.com/nuxt-ui-templates/dashboard --- 一个多列布局的仪表板。 ::::: :::::card --- icon: i-simple-icons-github target: _blank title: SaaS to: https://github.com/nuxt-ui-templates/saas --- 具有登陆页面、定价、文档和博客的模板。 ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Docs to: https://github.com/nuxt-ui-templates/docs --- 一个带有 `@nuxt/content` 的文档。 ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Landing to: https://github.com/nuxt-ui-templates/landing --- 一个可用作起点的登陆页面。 ::::: :::: ::: :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ```mdc :::card-group ::card --- title: Dashboard icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/dashboard target: _blank --- A dashboard with multi-column layout. :: ::card --- title: SaaS icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/saas target: _blank --- A template with landing, pricing, docs and blog. :: ::card --- title: Docs icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/docs target: _blank --- A documentation with `@nuxt/content`. :: ::card --- title: Landing icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/landing target: _blank --- A landing page you can use as starting point. :: ::: ``` ::: :: ### `Collapsible` 使用 `collapsible` 组件包装您的内容以在内容中显示 [Collapsible](https://ui.nuxt.com/components/collapsible){rel=""nofollow""}。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::collapsible | Prop | Default | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::collapsible | Prop | Default | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | :: ``` ::: :: ### `Field` 和 `FieldGroup` `field` 是一个在内容中显示的属性或参数。您可以通过 `field-group` 将它们分组在列表中。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::field-group{.my-0} :::::field{name="analytics" type="boolean"} Default to `false` \- Enables analytics for your project (coming soon). ::::: :::::field{name="blob" type="boolean"} Default to `false` \- Enables blob storage to store static assets, such as images, videos and more. ::::: :::::field{name="cache" type="boolean"} Default to `false` \- Enables cache storage to cache your server route responses or functions using Nitro's `cachedEventHandler` and `cachedFunction` ::::: :::::field{name="database" type="boolean"} Default to `false` \- Enables SQL database to store your application's data. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::field-group ::field{name="analytics" type="boolean"} Default to `false` - Enables analytics for your project (coming soon). :: ::field{name="blob" type="boolean"} Default to `false` - Enables blob storage to store static assets, such as images, videos and more. :: ::field{name="cache" type="boolean"} Default to `false` - Enables cache storage to cache your server route responses or functions using Nitro's `cachedEventHandler` and `cachedFunction` :: ::field{name="database" type="boolean"} Default to `false` - Enables SQL database to store your application's data. :: :: ``` ::: :: ### `Icon` 使用 `icon` 组件在内容中显示 [Icon](https://ui.nuxt.com/components/icon){rel=""nofollow""}。 ::code-preview :icon{name="i-simple-icons-nuxtdotjs"} #code ```mdc :icon{name="i-simple-icons-nuxtdotjs"} ``` :: ### `Kbd` 使用 `kbd` 组件在内容中显示 [Kbd](https://ui.nuxt.com/components/kbd){rel=""nofollow""}。 ::code-preview #code ```mdc :kbd{value="meta"} :kbd{value="K"} ``` :: ### `Tabs` 使用 `tabs` 和 `tabs-item` 组件在内容中显示 [Tabs](https://ui.nuxt.com/components/tabs){rel=""nofollow""}。 ::code-preview :::tabs{.w-full} ::::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :: ``` :::: ::::tabs-item{icon="i-lucide-eye" label="Preview"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: :::: ::: #code ````mdc ::tabs{.w-full} :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :::: ``` :::: :::tabs-item{icon="i-lucide-eye" label="Preview"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: ::: :: ```` :: ### `Steps` 用 Steps 组件包装您的标题以显示步骤列表。 使用 `level` 属性来定义哪个标题将用于步骤。 ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::steps{level="4"} #### Start a fresh new project ```bash [Terminal] npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/template ``` #### Run your dev server ```bash [Terminal] pnpm run dev ``` :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ````mdc ::steps{level="4"} #### 启动一个全新项目 ```bash [Terminal] npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/template ``` #### 启动您的开发服务器 ```bash [Terminal] pnpm run dev ``` :: ```` ::: :: # 图片与嵌入 ## Markdown 使用标准的 Markdown 语法来显示图片或视频。 ### 图片 ::code-preview ![Nuxt 社交图片](https://nuxt.com/new-social.jpg) #code ```mdc ![Nuxt 社交图片](https://nuxt.com/new-social.jpg) ``` :: 或者使用本地图片： ::code-preview ![夕阳下云海中的雪山](https://docs.mhaibaraai.cn/mountains.webp) #code ```mdc ![夕阳下云海中的雪山](/mountains.webp) ``` :: ::note{to="https://image.nuxt.com/"} Movk Nuxt Docs 在底层会使用 `` 组件，而不是原生的 `` 标签。 :: ### 视频 ::prose-code-preview :video{autoplay controls loop src="https://media.w3.org/2010/05/sintel/trailer.mp4"} #code ```mdc :video{autoplay controls loop src="https://media.w3.org/2010/05/sintel/trailer.mp4"} ``` :: ### # CommitChangelog ## 概述 根据指定文件路径，从 GitHub 仓库获取提交历史，以时间线形式展示。 ::callout :::collapsible{name="工作原理"} 1. **路径推断**：根据 `name` 属性或当前路由推断文件名 2. **命名转换**：支持多种文件命名格式（通过 `casing`参数控制） - `auto`（默认）：Vue 组件使用 PascalCase，其他文件使用 camelCase - `kebab`：保持 kebab-case（如 `use-user` → `use-user.ts`） - `camel`：转换为 camelCase（如 `use-user` → `useUser.ts`） - `pascal`：转换为 PascalCase（如 `use-user` → `UseUser.ts`） 3. **获取提交**：调用 GitHub API 获取指定文件的提交历史 4. **格式化显示**：将提交信息格式化为 Markdown，包含： - 提交 SHA（前 5 位）和链接 - 提交信息（移除范围标注） - Issue 引用链接（如 `#123`） - 内联代码高亮 ::: :: ## 前置要求 - **GitHub 配置**：在 `app.config.ts` 中配置 GitHub 相关信息。详见 [GitHub 集成配置](https://docs.mhaibaraai.cn/docs/getting-started/configuration#github-%E9%9B%86%E6%88%90)。 - **环境变量**：在 `.env`文件中配置 GitHub Token： ```bash NUXT_GITHUB_TOKEN=ghp_your_personal_access_token_here ``` ::warning{to="https://github.com/settings/tokens"} GitHub Token 需要具有读取仓库提交历史的权限（ `repo` 或 `public_repo` scope）。您可以在 GitHub Settings > Developer settings > Personal access tokens 创建新的 token。 :: ::tip 如果未配置 `NUXT_GITHUB_TOKEN` ，组件将不会报错，而是显示 "No recent changes"。 :: ## 用法 ### 基本用法 在您的 Markdown 文档中使用以下语法： ```md [md] :commit-changelog ``` 组件会自动根据当前页面路由推断组件名称，并获取对应文件的提交历史。 ### 显示 Vue 组件的提交历史 ```md [md] :commit-changelog{name="Accordion"} ``` 输出示例： - [`a1b2c`](https://github.com/.../commit/a1b2c3){rel=""nofollow""} — fix: 修复折叠动画延迟问题 [#45](https://github.com/.../issues/45){rel=""nofollow""} - [`d4e5f`](https://github.com/.../commit/d4e5f6){rel=""nofollow""} — feat: 添加 `disabled` 属性支持 ### 显示 TypeScript 文件的提交历史 ```md [md] :commit-changelog{suffix="ts" name="useColorMode"} ``` ### 按作者过滤提交 通过在 URL 查询参数中添加 `author` 可以只显示特定作者的提交： ```md [md] :commit-changelog{author="user@example.com"} ``` ::tip `author` 参数可以是 GitHub 用户名或邮箱地址。例如： `?author=octocat` 或 `?author=user@example.com` :: ### 使用 kebab-case 命名的文件 对于使用 `kebab-case` 命名的 `composables` 或 `utils` 文件： ```md [md] :commit-changelog{suffix="ts" name="use-user" casing="kebab" commitPath="composables"} ``` 这将查找 `composables/use-user.ts` 的提交历史。 ::tip 如果项目中的文件统一使用 `kebab-case` 命名，建议在 `app.config.ts` 中全局配置 `github.casing: 'kebab'`，这样就不需要在每个组件中重复指定。 ```ts [app.config.ts] export default defineAppConfig({ github: { casing: 'kebab', // 全局默认使用 kebab-case // 其他配置... } }) ``` :: ### 完整配置示例 ```md [md] ::commit-changelog --- commitPath: 'packages/core/src' prefix: 'components' suffix: 'ts' name: 'useUser' author: 'user@example.com' --- ``` ## API ### Props :component-props ## Changelog :commit-changelog # ComponentEmits ## 用法 在您的 Markdown 文档中使用以下语法： ```md [md] :component-emits{slug="你的组件名称"} ``` ## API ### Props :component-props ## Changelog :commit-changelog # ComponentExample ## 用法 `ComponentExample` 用于在文档中嵌入可交互的组件示例。它会自动加载组件,并展示实时预览和源代码。 ::warning 使用 `ComponentExample` 前,需要在 `nuxt.config.ts` 中配置示例组件目录,以确保组件被全局注册: ```ts import { createResolver } from '@nuxt/kit' const { resolve } = createResolver(import.meta.url) export default defineNuxtConfig({ modules: [ (_, nuxt) => { nuxt.hook('components:dirs', (dirs) => { dirs.unshift({ path: resolve('./app/components/content/examples'), pathPrefix: false, prefix: '', global: true }) }) } ] }) ``` 此配置将 `./app/components/content/examples` 目录下的所有组件注册为全局组件,使 `ComponentExample` 能够动态加载它们。 :: ### 基本用法 在您的 Markdown 文档中使用 `::component-example` 指令： ```md [md] :component-example{name="ButtonExample"} ``` ### 高级配置 ```md [md] ::component-example --- name: AccordionExample highlights: [10, 15, 20] collapse: true --- :: ``` ## API ### Props :component-props ### Slots :component-slots ## Changelog :commit-changelog # ComponentProps ## 用法 在您的 Markdown 文档中使用以下语法： ```md [md] :component-props{slug="你的组件名称"} ``` ## API ### Props :component-props ## Changelog :commit-changelog # ComponentSlots ## 用法 在您的 Markdown 文档中使用以下语法： ```md [md] :component-slots{slug="你的组件名称"} ``` ## API ### Props :component-props ## Changelog :commit-changelog # PageLastCommit ## 概述 `PageLastCommit` 组件用于显示当前文档页面的最后更新信息，包括： - **更新时间**：文件最后一次提交的时间 - **作者信息**：提交者的 GitHub 用户名（可点击跳转） - **提交信息**：最后一次提交的 commit message（可点击跳转到具体 commit） 该组件已内置于文档页面的页头区域，无需手动添加。 ## 效果展示 组件会在页面描述下方显示类似以下内容： > 最后更新于 **2025/11/26 14:37** 由 `mhaibaraai` 提交 `docs: 完善文档内容并新增模板说明` ## 前置要求 ### 1. GitHub Token 配置 在 `.env` 文件中配置 GitHub Personal Access Token： ```bash [.env] NUXT_GITHUB_TOKEN=ghp_your_personal_access_token_here ``` ::warning{to="https://github.com/settings/tokens"} GitHub Token 需要具有读取仓库提交历史的权限（ `repo` 或 `public_repo` scope）。 :: ### 2. GitHub 配置 确保在 `app.config.ts` 中正确配置了 GitHub 相关信息： ```ts [app.config.ts] export default defineAppConfig({ github: { rootDir: 'docs', // 文档所在目录 } }) ``` ## 自定义日期格式 通过 `dateFormat` 配置可以自定义日期显示格式： ```ts [app.config.ts] export default defineAppConfig({ github: { rootDir: 'docs', dateFormat: { locale: 'zh-CN', options: { year: 'numeric', month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit' } } } }) ``` ### 常用日期格式示例 | 配置 | 输出示例 | | ------------------------------------------------------------------------------------------- | ----------------- | | `{ year: 'numeric', month: 'short', day: 'numeric' }` | 2025年11月26日 | | `{ year: 'numeric', month: 'numeric', day: 'numeric' }` | 2025/11/26 | | `{ year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }` | 2025/11/26 14:37 | | `{ dateStyle: 'full' }` | 2025年11月26日星期三 | | `{ dateStyle: 'medium', timeStyle: 'short' }` | 2025年11月26日 14:37 | ::tip `dateFormat.options` 使用标准的 [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options){rel=""nofollow""} 配置。 :: ## PR Squash Merge 支持 组件智能处理 GitHub 的 PR squash merge 场景： - 当检测到提交者是 `web-flow`（GitHub 自动合并机器人）时 - 自动解析 commit message 中的 PR 编号（如 `#123`） - 获取实际的 PR 作者信息并显示 ## API ### Props :component-props ## Changelog :commit-changelog # fetchComponentExample ## 概述 获取组件的示例代码。 ```vue ``` ### 显示代码示例 ```vue ``` ## API ### `fetchComponentExample(name)`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 获取组件示例代码。 ### 参数 ::field-group :::field --- required: true name: name type: string --- 组件示例名称（PascalCase）。 ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # fetchComponentMeta ## 概述 获取 Vue 组件的元数据，包括 Props、Emits、Slots 等信息。 ```vue ``` ### 显示 Props 文档 ```vue ``` ## API ### `fetchComponentMeta(name)`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 获取组件元数据。 ### 参数 ::field-group :::field --- required: true name: name type: string --- 组件名称（PascalCase）。 ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useAnalytics ## 概述 ### 启用 Analytics 在 `app.config.ts` 中配置： ```ts [app.config.ts] export default defineAppConfig({ vercelAnalytics: { debug: true // 开发环境启用日志 } }) ``` ## 使用示例 ### 追踪按钮点击 ```vue ``` ### 内置事件追踪 ThemePicker 组件已集成 Analytics： ```ts // 主题选择器打开 track('Theme Picker Opened') // 主题设置变更 track('Theme Changed', { setting: 'primary', value: 'blue' }) // 主题导出 track('Theme Exported', { type: 'css' }) // 主题重置 track('Theme Reset') ``` ### 条件追踪 ```vue ``` ## API ### `useAnalytics()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 提供 Vercel Analytics 事件追踪，用于监控用户行为和站点性能。 ### 返回值 ::field-group :::field --- name: track type: "(event: string, properties?: Record) => void" --- 一个函数，用于追踪事件。接受事件名称和可选的事件属性对象。 ::::collapsible :::::field-group ::::::field --- required: true name: event type: string --- 事件名称。 :::::: ::::::field{name="properties" type="Record"} 可选的事件属性对象。 :::::: ::::: :::: ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useCategory ## 概述 管理文档的分类系统，方便对文档进行分组和导航。 ### 配置分类 在项目中创建 `composables/useCategory.ts` 覆盖默认配置： ```ts export function useCategory() { return { categories: { components: [ { id: 'content', title: 'Content Components', icon: 'i-lucide-component' }, { id: 'layout', title: 'Layout Components', icon: 'i-lucide-layout-dashboard' } ], composables: [ { id: 'navigation', title: 'Navigation', icon: 'i-lucide-compass' }, { id: 'ui', title: 'UI Utilities', icon: 'i-lucide-sparkles' } ] } } } ``` ### Frontmatter 中使用分类 ```md --- title: ComponentPropsLinks category: content --- ``` ## API ### `useCategory()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 返回分类配置。 ### 返回值 ::field-group :::field{name="categories" type="Record"} 分类配置对象，键为文档目录 slug。 ::::collapsible :::::field-group ::::::field --- required: true name: id type: string --- 分类 ID，对应 frontmatter 的 category 字段。 :::::: ::::::field --- required: true name: title type: string --- 分类显示标题。 :::::: ::::::field --- required: true name: icon type: string --- 分类图标类名。 :::::: ::::: :::: ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useFaq ## 概述 `useFaq()` 为 AI Chat 功能提供结构化的常见问题列表，帮助用户快速了解文档系统的核心功能。问题按类别组织，便于用户发现和查询。 ## 使用示例 ```ts [composables/useFaq.ts] export interface FaqItem { category: string items: string[] } export function useFaq() { const faqQuestions: FaqItem[] = [ { category: '快速开始', items: [ '如何安装？', '支持哪些框架？', '有演示站点吗？' ] }, { category: '核心功能', items: [ 'Markdown 语法支持哪些扩展？', '如何配置主题？', '支持暗色模式吗？' ] } ] return { faqQuestions } } ``` ## API ### `useFaq()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 返回常见问题配置。 ### 返回值 ::field-group :::field{name="faqQuestions" type="FaqItem[]"} 常见问题列表，按分类组织。 ::::collapsible :::::field-group ::::::field --- required: true name: category type: string --- 问题分类名称。 :::::: ::::::field --- required: true name: items type: string[] --- 该分类下的问题列表。 :::::: ::::: :::: ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useHeader ## 概述 `useHeader()` 配置 Header 组件的桌面端和移动端导航链接。 ### 默认实现 默认返回空数组： ```ts [composables/useHeader.ts] export function useHeader() { return { desktopLinks: computed(() => []), mobileLinks: computed(() => []) } } ``` ## 使用示例 ### 覆盖默认配置 在项目中创建 `composables/useHeader.ts` 覆盖默认配置： ```ts [composables/useHeader.ts] export function useHeader() { const route = useRoute() return { desktopLinks: computed(() => [ { label: '文档', to: '/docs', icon: 'i-lucide-book', active: route.path.startsWith('/docs') }, { label: 'API', to: '/api', icon: 'i-lucide-code', active: route.path.startsWith('/api') } ]), mobileLinks: computed(() => [ { label: '首页', to: '/', icon: 'i-lucide-square-play' }, { label: '文档', to: '/docs', icon: 'i-lucide-book' } ]) } } ``` ### 多语言支持 ```ts [composables/useHeader.ts] export function useHeader() { const { t } = useI18n() return { desktopLinks: computed(() => [ { label: t('nav.docs'), to: '/docs', icon: 'i-lucide-book' }, { label: t('nav.api'), to: '/api', icon: 'i-lucide-code' } ]), mobileLinks: computed(() => [ { label: t('nav.home'), to: '/', icon: 'i-lucide-square-play' }, { label: t('nav.docs'), to: '/docs', icon: 'i-lucide-book' } ]) } } ``` ## API ### `useHeader()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 返回 Header 导航链接配置。 ### 返回值 ::field-group :::field{name="desktopLinks" type="ComputedRef"} 桌面端导航菜单项。 ::: :::field{name="mobileLinks" type="ComputedRef"} 移动端导航菜单项。 ::: :: ### 链接对象字段 ::field-group :::field --- required: true name: label type: string --- 显示文本。 ::: :::field --- required: true name: to type: string --- 链接地址。 ::: :::field{name="icon" type="string"} 图标类名。 ::: :::field{name="active" type="boolean"} 是否激活状态。 ::: :::field{name="badge" type="string"} 徽章文本。 ::: :::field{name="children" type="NavigationLink[]"} 子菜单。 ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useNavigation ## 概述 管理文档导航结构，提供导航树处理和面包屑生成功能。 ## 使用示例 ### 基础用法 ```vue ``` ### 在 Layout 中使用 ```vue ``` ## API ### `useNavigation(navigation)`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 处理导航树，提供导航和面包屑功能。 ### 参数 ::field-group :::field --- required: true name: navigation type: Ref --- Nuxt Content 提供的导航数据。 ::: :: ### 返回值 ::field-group :::field{name="rootNavigation" type="ComputedRef"} 根级导航项数组。 ::: :::field --- name: navigationByCategory type: ComputedRef --- 按分类分组的当前页面子导航。 ::: :::field{name="findBreadcrumb" type="(path: string) => ContentNavigationItem[]"} 生成指定路径的面包屑导航。 ::: :: ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"} # useTheme ## 概述 `useTheme` 提供完整的主题定制能力，允许用户动态调整站点的视觉风格，包括颜色方案、字体选择、圆角大小、图标集以及明暗模式切换。所有配置自动持久化到 localStorage。 ### 主题配置项 - **颜色**：主色调和中性色配置 - **字体**：7 种预设字体系列 - **圆角**：5 种圆角半径选项 - **图标集**：Lucide / Phosphor / Tabler - **颜色模式**：light / dark / system ## 使用示例 ### 基础主题切换 ```vue ``` ### 字体和圆角定制 ```vue ``` ### 图标集切换 ```vue ``` ### 主题导出 ```vue ``` ### 主题重置 ```vue ``` ### 高级：黑色主色模式 ```vue ``` ## API ### `useTheme()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 返回主题配置管理对象，包含所有主题相关的状态和操作方法。 ### 返回值 ::field-group :::field{name="primary" type="Ref"} 主色调，从 Tailwind 颜色中选择（不包含中性色）。 ::: :::field{name="primaryColors" type="string[]"} 所有可用的主色选项数组。 ::: :::field{name="neutral" type="Ref"} 中性色，可选值： `slate` / `gray` / `zinc` / `neutral` / `stone` 。 ::: :::field{name="neutralColors" type="string[]"} 所有可用的中性色选项数组。 ::: :::field{name="radius" type="Ref"} 圆角半径（单位：rem），可选值： `0` / `0.125` / `0.25` / `0.375` / `0.5` 。 ::: :::field{name="radiuses" type="number[]"} 所有可用的圆角选项数组。 ::: :::field{name="font" type="Ref"} 字体系列，可选值： `Public Sans` / `DM Sans` / `Geist` / `Inter` / `Poppins` / `Outfit` / `Raleway` 。 ::: :::field{name="fonts" type="string[]"} 所有可用的字体选项数组。 ::: :::field{name="icon" type="Ref"} 图标集，可选值： `lucide` / `phosphor` / `tabler` 。 ::: :::field --- name: icons type: "Array<{ label: string; icon: string; value: string }>" --- 所有可用的图标集选项，每项包含标签、图标类名和值。 ::: :::field{name="mode" type="Ref<'light' | 'dark' | 'system'>"} 颜色模式，支持明亮、暗黑和跟随系统三种模式。 ::: :::field{name="modes" type="Array<{ label: string; icon: string }>"} 所有颜色模式选项，包含标签和对应图标。 ::: :::field{name="setBlackAsPrimary" type="(value: boolean) => void"} 设置是否使用黑色作为主色（明亮模式黑色，暗黑模式白色）。 ::::collapsible :::::field-group ::::::field --- required: true name: value type: boolean --- 是否启用黑色主色模式。 :::::: ::::: :::: ::: :::field{name="hasCSSChanges" type="Ref"} 计算属性，判断是否有 CSS 相关的自定义配置（圆角、字体、黑色主色）。 ::: :::field{name="hasAppConfigChanges" type="Ref"} 计算属性，判断是否有 App Config 相关的自定义配置（主色、中性色、图标集）。 ::: :::field{name="exportCSS" type="() => string"} 导出当前主题的 CSS 配置代码，包含 Tailwind CSS 变量声明。 ::: :::field{name="exportAppConfig" type="() => string"} 导出当前主题的 `app.config.ts` 配置代码。 ::: :::field{name="resetTheme" type="() => void"} 重置所有主题设置到默认值，并清除 localStorage 中的持久化数据。 ::: :: ## 持久化机制 所有主题配置会自动保存到 localStorage，键名格式为 `{站点名称}-ui-{配置项}`： - `{站点名称}-ui-primary`：主色配置 - `{站点名称}-ui-neutral`：中性色配置 - `{站点名称}-ui-radius`：圆角配置 - `{站点名称}-ui-font`：字体配置 - `{站点名称}-ui-icons`：图标集配置 - `{站点名称}-ui-black-as-primary`：黑色主色模式 ## Analytics 集成 当启用 Vercel Analytics 的 debug 模式时，所有主题变更都会被追踪： ```ts // 主题变更事件示例 track('Theme Changed', { setting: 'primary', value: 'blue' }) track('Theme Exported', { type: 'css' }) track('Theme Reset') ``` ## Changelog :commit-changelog{commit-path="layer/app/composables" suffix="ts"}