安装
用官方模板从零创建文档站,或把 @movk/nuxt-docs 作为 Layer 接入现有 Nuxt 项目。本页列出 default、i18n、module 三套模板的区别、运行环境要求与必须安装的依赖。
运行环境
- Node.js 22.22.3+(22.x)、24.15.0+(24.x)或 26+。内容数据库使用 Node.js 内置的
node:sqlite,无需安装better-sqlite3 - Nuxt 4.6.1+(4.x)、Tailwind CSS 4、
@nuxt/content3,三者均为 peer 依赖,需装在你的项目中
从模板创建
三套模板都已配置好 extends、首页与示例文档,区别如下:
| 模板 | 适用场景 | 包含 |
|---|---|---|
default | 通用文档站 | 首页、文档页、ESLint 与 TypeScript 检查 |
i18n | 多语言文档站 | 在 default 基础上启用 @nuxtjs/i18n,内置简体中文与英文两套内容 |
module | npm 包或 Nuxt 模块文档 | 在 default 基础上附带 releases.yml 版本发布页 |
把下面命令中的 default 换成需要的模板名:
pnpm dlx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
pnpm dev
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
npm run dev
yarn dlx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
yarn dev
bunx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
bun dev
nuxi init 会在创建后询问是否安装依赖。启动后访问 http://localhost:3000。
模板根目录的 .env.example 列出了可用的环境变量,复制为 .env 后按需填写:
.env
# 读取 GitHub 提交记录与版本发布,生产环境必需
NUXT_GITHUB_TOKEN=
# 填写后启用 AI Chat
AI_API_KEY=
# 可选:OpenAI 兼容端点,留空则走 AI Gateway
AI_BASE_URL=
模板默认不包含 AI Chat 依赖,填写
AI_API_KEY 前先按 AI 聊天 安装所需依赖,否则构建会报错并给出安装命令。接入现有项目
安装依赖
pnpm add @movk/nuxt-docs @nuxt/content tailwindcss
npm install @movk/nuxt-docs @nuxt/content tailwindcss
yarn add @movk/nuxt-docs @nuxt/content tailwindcss
bun add @movk/nuxt-docs @nuxt/content tailwindcss
@nuxt/content 必须装在应用自身的依赖中。Nuxt 生成的内容集合类型只有在应用作用域内解析到它才会生效,否则服务端 queryCollection 等会被推断为 never。扩展 Layer
nuxt.config.ts
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs']
})
创建第一篇文档
文档必须放在 content/docs/ 下,路由前缀固定为 /docs:
content/docs/1.getting-started/1.index.md
---
title: 简介
description: 这是我的第一篇文档。
---
## 开始
用 Markdown 写内容即可。
文件名的数字前缀只用于排序,上例的路由是 /docs/getting-started。站点首页由 content/index.md 渲染,也可以改用 app/pages/index.vue。更多约定见 项目结构。
可选依赖
默认关闭的功能需要额外安装依赖,启用后缺少依赖会在构建期报错并列出安装命令:
| 功能 | 依赖 |
|---|---|
| AI Chat | ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes |
| 组件文档 | nuxt-component-meta vue-component-meta prettier |
| Mermaid | mermaid dompurify |
| 无障碍检查 | @nuxt/a11y |
| 国际化 | @nuxtjs/i18n |
各功能的开启方式见 功能开关。
让 AI 助手协助搭建
文档站内置的 Agent Skills 可以安装到 Claude Code、Cursor 等 AI 助手中,让它按本主题的约定生成页面:
Terminal
npx skills add https://docs.mhaibaraai.cn
你的站点同样会把 skills/ 目录发布出去,见 Agent Skills。