create-docs

创建文档

为任意项目生成完整、可用于生产环境的文档站点。

工作流

1. 分析 - 检测包管理器和 monorepo 结构，读取上下文
2. 初始化 - 创建配置正确的文档目录
3. 生成 - 使用模板编写文档页面
4. 配置 - 设置 AI 集成（MCP、llms.txt）
5. 完成 - 提供正确的命令作为后续步骤

---

包管理器参考

根据锁文件检测；如果未找到，则默认使用 npm：

锁文件	PM	安装	运行	添加
pnpm-lock.yaml	pnpm	pnpm install	pnpm run	pnpm add
package-lock.json	npm	npm install	npm run	npm install
yarn.lock	yarn	yarn install	yarn	yarn add
bun.lockb	bun	bun install	bun run	bun add

在下方的命令中使用 [pm] 作为占位符。

---

第 1 步：分析项目

检测项目结构

Check for:
├── pnpm-workspace.yaml   → pnpm monorepo
├── turbo.json            → Turborepo monorepo
├── lerna.json            → Lerna monorepo
├── nx.json               → Nx monorepo
├── apps/                 → Apps directory (monorepo)
├── packages/             → Packages directory (monorepo)
├── docs/                 → Existing docs (avoid overwriting)
├── README.md             → Main documentation source
└── src/ or lib/          → Source code location

确定文档位置

项目类型	目标目录	工作区入口
标准项目	./docs	N/A
含 apps/ 的 monorepo	./apps/docs	apps/docs
含 packages/ 的 monorepo	./docs	docs
已有 docs/ 文件夹	询问用户或使用 ./documentation	—

读取上下文文件

文件	提取内容
README.md	项目名称、描述、功能、用法示例
package.json	名称、描述、依赖项、仓库 URL
src/ 或 lib/	导出的函数、用于 API 文档的组合式函数

检测 i18n 需求

检查项目是否需要多语言文档：

指标	操作
依赖项中包含 @nuxtjs/i18n	使用 i18n 模板
存在 locales/ 或 i18n/ 文件夹	使用 i18n 模板
存在多个语言版本的 README 文件	使用 i18n 模板
用户明确提及多种语言	使用 i18n 模板
以上均不符合	使用默认模板

---

第 2 步：初始化文档

创建目录结构

默认模板：

[docs-location]/
├── app/                            # Optional: for customization
│   ├── app.config.ts
│   ├── components/
│   ├── layouts/
│   └── pages/
├── content/
│   ├── index.md
│   └── 1.getting-started/
│       ├── .navigation.yml
│       └── 1.introduction.md
├── public/
│   └── favicon.ico
├── package.json
└── .gitignore

i18n 模板（检测到多语言时）：

[docs-location]/
├── app/
│   └── app.config.ts
├── content/
│   ├── en/
│   │   ├── index.md
│   │   └── 1.getting-started/
│   │       ├── .navigation.yml
│   │       └── 1.introduction.md
│   └── fr/                         # Or other detected languages
│       ├── index.md
│       └── 1.getting-started/
│           ├── .navigation.yml
│           └── 1.introduction.md
├── nuxt.config.ts                  # Required for i18n config
├── public/
│   └── favicon.ico
├── package.json
└── .gitignore

创建 package.json

默认：

{
  "name": "[project-name]-docs",
  "private": true,
  "scripts": {
    "dev": "nuxt dev --extends docus",
    "build": "nuxt build --extends docus",
    "generate": "nuxt generate --extends docus",
    "preview": "nuxt preview --extends docus"
  },
  "dependencies": {
    "docus": "latest",
    "better-sqlite3": "^12.5.0",
    "nuxt": "^4.2.2"
  }
}

i18n（添加 @nuxtjs/i18n）：

{
  "name": "[project-name]-docs",
  "private": true,
  "scripts": {
    "dev": "nuxt dev --extends docus",
    "build": "nuxt build --extends docus",
    "generate": "nuxt generate --extends docus",
    "preview": "nuxt preview --extends docus"
  },
  "dependencies": {
    "@nuxtjs/i18n": "^10.2.1",
    "docus": "latest",
    "better-sqlite3": "^12.5.0",
    "nuxt": "^4.2.2"
  }
}

创建 nuxt.config.ts（仅 i18n）

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: [
      { code: 'en', language: 'en-US', name: 'English' },
      { code: 'fr', language: 'fr-FR', name: 'Français' }
    ],
    defaultLocale: 'en'
  }
})

创建 .gitignore

node_modules
.nuxt
.output
.data
dist

更新 monorepo 配置（如适用）

pnpm monorepo

1. 将文档添加到工作区，并配置 onlyBuiltDependencies（better-sqlite3 必需）：

packages:
  - 'apps/*'
  - 'docs'

onlyBuiltDependencies:
  - better-sqlite3

2. 在根目录的 package.json 中添加 dev 脚本：

{
  "scripts": {
    "docs:dev": "pnpm run --filter [docs-package-name] dev"
  }
}

或者使用目录路径：

{
  "scripts": {
    "docs:dev": "cd docs && pnpm dev"
  }
}

npm/yarn monorepo

{
  "workspaces": ["apps/*", "docs"],
  "scripts": {
    "docs:dev": "npm run dev --workspace=docs"
  }
}

---

第 3 步：生成文档

使用 references/templates.md 中的模板。

重要：MDC 组件命名

MDC 中的所有 Nuxt UI 组件都必须使用 u- 前缀：

正确	错误
::u-page-hero	::page-hero
::u-page-section	::page-section
:::u-page-feature	:::page-feature
:::u-button	:::button
::::u-page-card	::::page-card

如果缺少 u- 前缀，Vue 将无法解析这些组件。

文档结构

content/
├── index.md                        # Landing page
├── 1.getting-started/
│   ├── .navigation.yml
│   ├── 1.introduction.md
│   └── 2.installation.md
├── 2.guide/
│   ├── .navigation.yml
│   ├── 1.configuration.md
│   ├── 2.authentication.md
│   └── 3.deployment.md
└── 3.api/                          # If applicable
    ├── .navigation.yml
    └── 1.reference.md

生成页面

1. 着陆页（index.md）- Hero + 功能网格
2. 简介 - 是什么、为何使用、使用场景
3. 安装 - 前置条件、安装命令
4. 指南页面 - 使用基于操作的 H2 标题编写功能文档

写作风格请参阅 references/writing-guide.md。 MDC 组件请参阅 references/mdc-components.md。

---

第 4 步：配置 AI 集成

Docus 会自动包含 MCP 服务（/mcp）并生成 llms.txt。无需配置。

不要在着陆页中添加 AI 集成部分。 这些功能会自动运行。

也可以选择在简介页面中提及：

::note
This documentation includes AI integration with MCP server and automatic `llms.txt` generation.
::

可选：app.config.ts

export default defineAppConfig({
  docus: {
    name: '[Project Name]',
    description: '[Project description]',
    url: 'https://[docs-url]',
    socials: {
      github: '[org]/[repo]'
    }
  }
})

可选：主题自定义

如果项目有设计系统或品牌色，请自定义文档主题。

自定义 CSS

创建 app/assets/css/main.css：

@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  /* Custom font */
  --font-sans: 'Inter', sans-serif;

  /* Custom container width */
  --ui-container: 90rem;

  /* Custom primary color (use project brand color) */
  --color-primary-50: oklch(0.97 0.02 250);
  --color-primary-500: oklch(0.55 0.2 250);
  --color-primary-900: oklch(0.25 0.1 250);
}

扩展版 app.config.ts

export default defineAppConfig({
  docus: {
    name: '[Project Name]',
    description: '[Project description]',
    url: 'https://[docs-url]',
    socials: {
      github: '[org]/[repo]',
      x: '@[handle]'
    }
  },
  // Customize UI components
  ui: {
    colors: {
      primary: 'emerald',
      neutral: 'zinc',
    },
    pageHero: {
      slots: {
        title: 'font-semibold sm:text-6xl'
      }
    }
  }
})

---

第 5 步：完成

使用检测到的包管理器提供说明。

标准项目

Documentation created in [docs-location]

To start:

  cd [docs-location]
  [pm] install
  [pm] run dev

Available at http://localhost:3000

Monorepo

Documentation created in [docs-location]

To start from root:

  [pm] install
  [pm] run docs:dev

Or from docs directory:

  cd [docs-location]
  [pm] run dev

Available at http://localhost:3000

包含的功能

• 全文搜索
• 深色模式
• 面向 AI 工具的 MCP 服务（/mcp）
• 大模型集成（/llms.txt）
• 针对 SEO 进行了优化

后续步骤

1. 检查生成的内容
2. 在 content/2.guide/ 中添加更多指南
3. 在 app.config.ts 中自定义主题
4. 部署到 Vercel/Netlify/Cloudflare

建议的后续工作

创建文档后，建议进行以下改进：

Your documentation is ready!

Would you like me to:
- **Customize the UI** - Match your brand colors and style
- **Enhance the landing page** - Add feature cards, code previews, visuals
- **Add i18n support** - Multi-language documentation
- **Set up deployment** - Deploy to Vercel, Netlify, or Cloudflare

Let me know what you'd like to improve!

---

部署

平台	命令	输出
Vercel	npx vercel --prod	自动检测
Netlify	[pm] run generate	.output/public
Cloudflare Pages	[pm] run generate	.output/public
GitHub Pages	[pm] run generate	.output/public

---

示例：auth-utils

检测结果： pnpm Monorepo，包位于 packages/

生成的结构：

docs/
├── content/
│   ├── index.md
│   ├── 1.getting-started/
│   │   ├── .navigation.yml
│   │   ├── 1.introduction.md
│   │   └── 2.installation.md
│   ├── 2.guide/
│   │   ├── .navigation.yml
│   │   ├── 1.authentication.md
│   │   ├── 2.oauth-providers.md
│   │   └── 3.sessions.md
│   └── 3.api/
│       ├── .navigation.yml
│       └── 1.composables.md
├── public/
│   └── favicon.ico
├── package.json
└── .gitignore

authentication.md 内部内容（基于操作的 H2 标题）：

## Add basic authentication
## Protect your routes
## Handle login redirects
## Customize the session