开发环境

适用对象

• 维护 cssadoc 仓库的成员

环境搭建

1. 安装 Node.js >= 20

2. 克隆仓库并安装依赖：

   git clone <仓库地址>
   cd cssadoc
   npm install

3. 启动开发或预览：

   npm start          # 热更新开发
   # 或
   npm run build && npm run serve   # 生产构建预览

推荐工具

工具	用途
VS Code / Cursor	编辑 Markdown 与 TypeScript
Markdown 预览插件	本地快速看排版（最终以 Docusaurus 渲染为准）
Git	版本管理与 PR

文档写作辅助

仓库内提供 Cursor Skill：

.cursor/skills/doc-writing/SKILL.md

其中定义 Diátaxis 目录映射、Mermaid 规范等，AI 辅助写作或人工维护均可参考。

常用命令速查

npm start              # 开发服务器
npm run build          # 生产构建
npm run serve          # 预览 build/
npm run preview        # build + wrangler dev
npm run deploy         # 构建并部署至 Cloudflare
npm run typecheck      # TS 类型检查
npm run clear          # 清理 Docusaurus 缓存
npm run write-translations   # 提取 i18n 字符串

常见错误

• ❌ Node 版本过低导致 Docusaurus 3 安装或构建失败
• ❌ 未 npm install 直接运行脚本
• ❌ 只改 Markdown 从不跑 build，合并后才发现链接错误