83 lines
3.8 KiB
Markdown
83 lines
3.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
SuBlog（尼克的小窝）— 个人技术博客，基于 Nuxt 3 + TypeScript，使用 @nuxt/content v3 管理 Markdown 文章。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
pnpm dev # 启动开发服务器
|
||
pnpm build # 构建生产版本
|
||
pnpm generate # 静态站点生成
|
||
pnpm preview # 预览构建产物
|
||
pnpm new-post <name> # 创建新文章（自动生成 frontmatter 和图片目录）
|
||
```
|
||
|
||
项目使用 pnpm 作为包管理器。
|
||
|
||
## 架构要点
|
||
|
||
### 内容系统
|
||
- 文章放在 `content/posts/<slug>/index.md`，图片放在同级 `img/` 目录
|
||
- 使用 @nuxt/content v3 的 `queryCollection('posts')` API 查询文章
|
||
- frontmatter 字段：`title`, `published`(日期), `description`, `image`, `draft`, `tags`, `pinned`
|
||
- `pinned` 字段控制文章置顶排序
|
||
- 构建时 `nuxt.config.ts` 中的 hook 自动将 `content/posts/<slug>/img/` 复制到产物目录
|
||
- 开发模式图片通过 `server/routes/posts/[slug]/img/[...file].ts` 读取源文件
|
||
|
||
### 新增文章流程
|
||
1. 执行 `pnpm new-post <slug>` 自动生成目录结构和模板
|
||
2. 脚本会创建 `content/posts/<slug>/index.md`（含 frontmatter 模板）和 `content/posts/<slug>/img/` 目录
|
||
3. 填写 frontmatter（`description`、`tags` 必填），编写正文
|
||
4. 封面图放在 `img/` 目录下，路径为 `/posts/<slug>/img/cover.jpg`
|
||
|
||
### 页面路由
|
||
- `pages/index.vue` — 首页（个人名片、3D 技术栈头像、社交卡片、导航、网易云热评、不蒜子计数、文章更新入口）
|
||
- `pages/posts/index.vue` — 文章列表（搜索、标签过滤、分页）
|
||
- `pages/posts/[slug].vue` — 文章详情（Giscus 评论、右侧 TOC 目录）
|
||
- `pages/[...slug].vue` — 兜底路由
|
||
- 其他页面：cover(封面制作)、friends(友链)、sponsor(赞助)、about(关于)
|
||
|
||
### 组件分层
|
||
- `components/layout/` — NavBar（面包屑导航 + 头像旋转）、AvatarOrbit（首页 3D 技术栈头像）、Footer、ThemeToggle
|
||
- `components/blog/` — PostCard、PostToc（基于 IntersectionObserver 的目录）、Giscus
|
||
- `components/content/ProseImg.vue` — 覆盖 @nuxt/content 默认图片组件，支持相对路径解析
|
||
|
||
### 工具层
|
||
- `composables/usePostSearch.ts` — 客户端搜索 composable，支持标题/描述/正文/标签多维过滤和高亮
|
||
- `utils/content-ast.ts` — Nuxt Content v3 AST 工具函数（文本提取、标题提取、slugify、去重）
|
||
- `config/site.ts` — 全站配置（站点信息、导航、社交链接、友链、赞助、Giscus）
|
||
|
||
### 主题与样式
|
||
- Tailwind CSS + `@tailwindcss/typography`，暗色模式使用 `class` 策略
|
||
- CSS 变量定义在 `assets/css/main.css`（`--color-bg`, `--color-primary` 等）
|
||
- 暗色模式通过 `.dark` class 切换
|
||
- 动画类：`anim-fade-in-up`、`anim-delay-N`
|
||
|
||
### 服务端
|
||
- `server/routes/api/wyy.ts` — 网易云热评 API 代理
|
||
|
||
## 开发规范
|
||
|
||
### 文章标签规范
|
||
- 使用语言/框架的官方名称，首字母大写：`Go`（非 Golang）、`TypeScript`（非 typescript）
|
||
- 框架/库名保持官方写法：`Nuxt`、`SvelteKit`、`Tailwind CSS`、`Docker`
|
||
- 中文分类标签：`运维`、`后端`、`前端框架`、`踩坑`、`博客`
|
||
- 缩写保持大写：`MCP`、`CSS`、`API`、`SQL`
|
||
|
||
### 工作流程
|
||
- 效率至上：快速单元式开发
|
||
- 改完即退：完成代码修改后立即退出，用户会手动测试
|
||
- 单元提交：每个功能/修改单独提交到 Git
|
||
- 非用户要求不输出多余内容
|
||
|
||
### 编辑规则
|
||
- 编辑文件仅使用 Read 和 Edit 工具，不使用 Python/PowerShell/Bash 修改文件
|
||
- Edit 工具使用函数签名等唯一字符串做锚点，避免 tab 缩进匹配问题
|
||
|
||
### Git 提交规范
|
||
- `feat:` 新功能 | `fix:` 修复 | `refactor:` 重构 | `style:` 样式 | `perf:` 性能 | `chore:` 构建/工具/配置
|