@movk/nuxt-docs

v1.17.0

Published

26 minutes ago

Modern Nuxt 4 documentation theme with auto-generated component docs, AI chat assistant, MCP server, and complete developer experience optimization.

0High
0Medium
0Low

movk

基于 Nuxt 4 的现代文档主题，集成组件自动化文档、AI 聊天助手、MCP Server 和完整的开发者体验优化

使用此主题可以快速构建美观、专业、智能的文档网站，内置组件文档自动生成、AI 聊天助手、MCP Server 支持、SEO 优化、暗黑模式、全文搜索等功能。

📖 在线文档

✨ 特性

此主题集成了一系列旨在优化文档管理体验的强大功能：

🤖 AI 增强体验

AI 聊天助手 - 内置智能文档助手，基于 Vercel AI SDK 支持多种 LLM 模型
MCP Server 支持 - 集成 Model Context Protocol 服务器，为 AI 助手提供结构化的文档访问能力
LLM 优化 - 通过 nuxt-llms 模块自动生成 llms.txt 和 llms-full.txt，为 AI 工具提供优化的文档索引
流式响应 - 支持 AI 响应流式输出和代码高亮，配合 shiki-stream 实现实时语法高亮渲染

AI 助手 Skill

Agent Skills 是一种开放格式，允许 AI 代理（Claude Code、Cursor、Windsurf 等）自动发现并加载文档站的专属工作流。Movk Nuxt Docs 将 skills/ 目录下的所有技能自动发布到 /.well-known/skills/ 端点。

内置技能：

create-docs - 为任意项目生成基于 Movk Nuxt Docs 的完整文档网站
review-docs - 审查文档质量，检查清晰度、SEO 和技术正确性

一键安装到 AI 工具：

npx skills add https://docs.mhaibaraai.cn

详见 Agent Skills 文档。

🧩 自动化文档生成

组件元数据自动提取 - 基于 nuxt-component-meta 自动提取 Vue 组件的 Props、Slots、Emits 定义
交互式示例展示 - 通过 ComponentExample 组件自动加载和渲染组件示例，支持代码高亮和实时预览
Git 提交历史集成 - 使用 CommitChangelog 和 PageLastCommit 组件自动展示文件的提交历史记录
类型定义高亮 - 智能解析 TypeScript 类型定义，支持内联类型高亮和类型导航

🎨 开发者体验

⚡ 基于 Nuxt 4 - 充分利用最新的 Nuxt 框架，实现卓越性能
🎨 采用 Nuxt UI - 集成全面的 UI 组件库，开箱即用
📝 MDC 语法增强 - 支持 Markdown 与 Vue 组件的无缝集成
📊 Mermaid 图表 - 可选按需启用，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
🔍 全文搜索 - 基于 Nuxt Content 的 ContentSearch 组件，支持键盘快捷键（⌘K）
🌙 暗黑模式 - 支持亮色/暗色主题切换
📱 响应式设计 - 移动优先的响应式布局
🚀 SEO 优化 - 内置 SEO 优化功能
🎯 TypeScript 支持 - 完整的 TypeScript 类型支持

🚀 快速开始

使用模板创建项目

根据您的需求选择合适的模板：

📚 完整文档站点（推荐）

适合构建完整的文档网站，包含 ESLint、TypeScript 检查等开发工具。

# 使用完整模板创建新项目
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
pnpm dev

📦 模块文档站点（精简）

适合为 npm 包或库快速创建文档，内置 Release 页面展示版本发布历史，无额外开发工具。

# 使用模块模板创建新项目
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/module my-module-docs
cd my-module-docs
pnpm dev

访问 http://localhost:3000 查看你的文档网站。

作为 Layer 使用

在现有 Nuxt 项目中使用 Movk Nuxt Docs 作为 layer：

pnpm add @movk/nuxt-docs better-sqlite3 tailwindcss

在 nuxt.config.ts 中配置：

export default defineNuxtConfig({
+  extends: ['@movk/nuxt-docs']
})

📁 项目结构

模板项目结构

使用模板创建的项目结构（以 default 模板为例）：

my-docs/
├── app/
│   └── composables/             # 自定义 Composables
├── content/                     # Markdown 内容
│   ├── index.md                 # 首页
│   └── docs/                    # 文档页面
├── public/                      # 静态资源
├── nuxt.config.ts               # Nuxt 配置
├── tsconfig.json                # TypeScript 配置
├── package.json                 # 依赖与脚本
├── .env.example                # 环境变量示例
└── pnpm-workspace.yaml          # pnpm 工作区配置

Monorepo 结构

本仓库采用 monorepo 结构：

movk-nuxt-docs/
├── docs/                        # 官方文档站点
├── layer/                       # @movk/nuxt-docs layer 包
├── templates/
│   ├── default/                 # 完整文档站点模板
│   └── module/                  # 模块文档站点模板（精简）
└── scripts/                     # 构建脚本

📝 内容编写

基础 Markdown

---
title: 页面标题
description: 页面描述
---

# 标题

这是一段普通的文本内容。

## 二级标题

- 列表项 1
- 列表项 2

MDC 语法

::card
---
title: 卡片标题
icon: i-lucide-rocket
---
卡片内容
::

了解更多关于 MDC 语法，请查看 Nuxt Content 文档。

Mermaid 图表

Mermaid 是可选功能，默认不启用。先安装依赖，再开启配置：

pnpm add mermaid dompurify

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],

  movkNuxtDocs: {
    mermaid: true
  }
})

启用后，使用 ```mermaid 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：

```mermaid
graph TD
A[开始] --> B{是否有效?}
B -->|是| C[处理数据]
B -->|否| D[显示错误]
C --> E[完成]
D --> E
```

主要特性：

🎨 自动主题切换（深色/浅色模式）
🔄 懒加载（仅在可见时渲染）
📋 一键复制图表代码
🖼️ 全屏查看功能
🔒 安全渲染（DOMPurify 清理）

支持的图表类型：

流程图（flowchart/graph）：用于展示流程和决策
时序图（sequenceDiagram）：用于展示交互时序
类图（classDiagram）：用于展示类关系
状态图（stateDiagram）：用于展示状态转换
甘特图（gantt）：用于展示项目时间线
饼图（pie）：用于展示数据占比
Git 图（gitGraph）：用于展示分支历史
以及更多 Mermaid 支持的图表类型

无障碍支持（A11y）

Movk Nuxt Docs 默认启用 @nuxt/a11y。如需关闭，可在 movkNuxtDocs 中设置：

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],

  movkNuxtDocs: {
    a11y: false
  }
})

🛠️ 开发

本地开发

# 克隆项目
git clone https://github.com/mhaibaraai/movk-nuxt-docs.git
# 进入项目目录
cd movk-nuxt-docs
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev

开发服务器将在 http://localhost:3000 启动。

构建生产版本

# 构建应用
pnpm build
# 本地预览生产构建
pnpm preview

发布

# 发布 layer 到 npm
pnpm release:layer
# 发布完整项目
pnpm release

⚡ 技术栈

本项目基于以下优秀的开源项目构建：

核心框架

Nuxt 4 - Web 框架
Nuxt Content - 基于文件的 CMS
Nuxt UI - UI 组件库
Tailwind CSS 4 - CSS 框架

AI 集成

Vercel AI SDK - AI 集成框架
Nuxt LLMs - LLM 优化
@nuxtjs/mcp-toolkit - MCP Server 支持
Shiki - 代码语法高亮
Shiki Stream - 流式代码高亮

功能增强

Nuxt Component Meta - 组件元数据提取
Nuxt Image - 图片优化
Nuxt SEO - SEO 优化
Octokit - GitHub API 集成

📖 文档

访问 Movk Nuxt Docs 文档了解详细的使用指南和 API 文档。

🙏 致谢

本项目基于以下优秀项目构建或受其启发：

Docus - 由 Nuxt Content 团队开发的文档主题
Nuxt UI Docs Template - Nuxt UI 官方文档模板