安装

用官方模板从零创建文档站,或把 @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/content 3,三者均为 peer 依赖,需装在你的项目中

从模板创建

三套模板都已配置好 extends、首页与示例文档,区别如下:

模板适用场景包含
default通用文档站首页、文档页、ESLint 与 TypeScript 检查
i18n多语言文档站在 default 基础上启用 @nuxtjs/i18n,内置简体中文与英文两套内容
modulenpm 包或 Nuxt 模块文档在 default 基础上附带 releases.yml 版本发布页

把下面命令中的 default 换成需要的模板名:

pnpm dlx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs
cd my-docs
pnpm 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
@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 Chatai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
组件文档nuxt-component-meta vue-component-meta prettier
Mermaidmermaid dompurify
无障碍检查@nuxt/a11y
国际化@nuxtjs/i18n

各功能的开启方式见 功能开关。

让 AI 助手协助搭建

文档站内置的 Agent Skills 可以安装到 Claude Code、Cursor 等 AI 助手中,让它按本主题的约定生成页面:

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

你的站点同样会把 skills/ 目录发布出去,见 Agent Skills。

Copyright © 2024 - 2026