/docs-site

搭建 VitePress 文档站并部署到 Cloudflare Pages。

搭建 VitePress 文档站

为项目 "$ARGUMENTS" 搭建 VitePress 文档站并配置 Cloudflare Pages 部署。

步骤

Step 1: 确认需求

使用 AskUserQuestion 向用户确认：

站点名称 — 用于 <title> 和首页标题（默认取项目名）
目录结构 — 文档源文件在哪里？（默认 docs/）
是否需要密码保护 — Cloudflare Pages Functions 中间件方案（默认否）
Cloudflare Pages 项目名 — 用于 wrangler pages deploy（默认取项目名的 kebab-case）

Step 2: 初始化 VitePress 项目

在项目根目录下创建 site/ 目录：

site/
├── package.json         # scripts: dev / build / preview
├── .vitepress/
│   ├── config.mts       # VitePress 配置
│   └── theme/
│       ├── index.ts     # 主题入口（扩展默认主题）
│       └── style.css    # 自定义样式
├── src/                  # 文档源文件（gitignore，构建时由 sync 脚本生成）
└── sync.mjs             # 同步脚本：从项目源目录复制到 src/

package.json 关键配置：

json

{
  "private": true,
  "type": "module",
  "scripts": {
    "sync": "node sync.mjs",
    "dev": "node sync.mjs && vitepress dev",
    "build": "node sync.mjs && vitepress build",
    "preview": "vitepress preview"
  },
  "devDependencies": {
    "vitepress": "^1.6.3"
  }
}

config.mts 基础结构：

import { defineConfig } from 'vitepress'

export default defineConfig({
  srcDir: 'src',
  lang: 'zh-CN',
  title: '[站点名称]',
  description: '[一句话描述]',
  head: [
    ['meta', { name: 'robots', content: 'noindex, nofollow' }],
  ],
  themeConfig: {
    nav: [/* 根据文档结构生成 */],
    sidebar: {/* 根据文档结构生成 */},
    search: { provider: 'local' },
  },
})

sync.mjs — 从项目文档目录同步到 site/src/：

清空 src/ → 遍历源目录 → 处理链接重写 → 写入 src/
如果源文件包含中文文件名，建立 slug 映射表（中文名 → 英文 slug）
生成首页 index.md（VitePress hero layout）

theme/index.ts — 主题入口：

import DefaultTheme from 'vitepress/theme'
import './style.css'
export default DefaultTheme

theme/style.css — 自定义样式（深蓝品牌色 + 中文排版优化）：

css

/* ── Brand colors & typography ───────────────────────────────────── */

:root {
  --vp-c-brand-1: #3451b2;
  --vp-c-brand-2: #3a5ccc;
  --vp-c-brand-3: #5672cd;
  --vp-font-family-base: "Noto Sans SC", "PingFang SC", "Microsoft YaHei",
    sans-serif;
  --vp-font-family-mono: "JetBrains Mono", "Fira Code", monospace;
}

.dark {
  --vp-c-brand-1: #6b8de5;
  --vp-c-brand-2: #5672cd;
  --vp-c-brand-3: #3a5ccc;
}

.vp-doc {
  line-height: 1.8;
}

.vp-doc p {
  margin: 1em 0;
}

/* ── Content width — wider after disabling aside ────────────────── */

.VPDoc:not(.has-aside) .content-container {
  max-width: 840px !important;
}

/* ── Headings — visual hierarchy ────────────────────────────────── */

.vp-doc h2 {
  padding-left: 0.8em;
  border-left: 4px solid var(--vp-c-brand-1);
  border-bottom: 1px solid var(--vp-c-divider);
  padding-bottom: 0.4em;
}

/* ── Code blocks — rounded & subtle shadow ──────────────────────── */

.vp-doc div[class*="language-"] {
  border-radius: 8px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.06);
}

.dark .vp-doc div[class*="language-"] {
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
}

/* ── Tables — zebra stripes, rounded, hover ─────────────────────── */

.vp-doc table {
  border-radius: 8px;
  overflow: hidden;
}

.vp-doc tbody tr:nth-child(even) {
  background-color: var(--vp-c-bg-soft);
}

.vp-doc tbody tr:hover {
  background-color: var(--vp-c-bg-mute);
}

/* ── Sidebar — group titles & active highlight ──────────────────── */

.VPSidebarItem.level-0 > .item > .text {
  font-weight: 700;
  color: var(--vp-c-text-1);
}

.VPSidebarItem.is-active > .item > .link > .text {
  color: var(--vp-c-brand-1) !important;
  font-weight: 600;
}

Step 3: 生成文档模板

根据项目类型生成初始文档：

首页 index.md — hero layout，包含项目名、描述、快速链接
快速上手 — 如果项目有 README 或 QUICKSTART，同步过来
PRD/Spec — 如果存在 docs/spec.md（/spec 产物），同步为独立页面

规则：

不创建空壳文档，只同步已有内容
模板对齐 /spec 的输出格式（如果有 spec.md）
文档页面保留原始 Markdown 格式，不额外包装

Step 4: 配置部署

推荐方式：Git 集成（推送即部署）

在 Cloudflare Pages Dashboard 中创建项目并连接 Git 仓库：

Workers & Pages → Create → Pages → Connect to Git
选择仓库，配置构建设置：
- Production branch: main
- Build command: npm run build
- Build output directory: .vitepress/dist
- Root directory: site
保存后，每次 git push 自动触发构建部署

备用方式：手动 CLI 部署

bash

cd site && npm run build && npx wrangler pages deploy .vitepress/dist \
  --project-name=[项目名]

在项目 CLAUDE.md 中记录所选部署方式和本地开发命令：

bash

# 本地预览
cd site && npm run dev

# 构建验证
cd site && npm run build

如果用户选择了密码保护：

创建 site/functions/_middleware.ts：

SITE_PASSWORD 环境变量控制密码（不设置 = 无认证，本地开发友好）
HttpOnly cookie 认证，7 天过期
Token = SHA-256("[project-name]:{password}")
POST /__auth 验证密码，GET /__logout 清除 cookie

在 Cloudflare Pages Dashboard 中设置 SITE_PASSWORD 环境变量。

Step 5: 验证

安装依赖：cd site && npm install
构建验证：cd site && npm run build
本地预览：cd site && npm run preview
确认页面正常渲染

关键约束

不过度配置 — 只生成项目实际需要的页面和导航，后续按需扩展
sync 脚本保持简单 — 文件复制 + 链接重写，不做复杂转换
src/ 目录加入 .gitignore — 构建产物不入库，每次 build 前由 sync 生成
优先 Git 集成部署 — 推送即发布，手动 CLI 部署仅作备用

IMPORTANT：这是一次性设置型技能。站点搭好后，后续维护只需 git push（Git 集成）或 cd site && npm run build && npx wrangler pages deploy ...（手动）。

/docs-site ​

搭建 VitePress 文档站 ​

步骤 ​

Step 1: 确认需求 ​

Step 2: 初始化 VitePress 项目 ​

Step 3: 生成文档模板 ​

Step 4: 配置部署 ​

Step 5: 验证 ​

关键约束 ​