# 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` 读取源文件

### 页面路由
- `pages/index.vue` — 首页（社交卡片、导航、网易云热评、不蒜子计数）
- `pages/posts/index.vue` — 文章列表（搜索、标签过滤、分页）
- `pages/posts/[slug].vue` — 文章详情（Giscus 评论、右侧 TOC 目录）
- `pages/[...slug].vue` — 兜底路由
- 其他页面：cover(封面制作)、friends(友链)、sponsor(赞助)、about(关于)

### 组件分层
- `components/layout/` — NavBar（面包屑导航 + 头像旋转）、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 代理

## 开发规范

### 工作流程
- 效率至上：快速单元式开发
- 改完即退：完成代码修改后立即退出，用户会手动测试
- 单元提交：每个功能/修改单独提交到 Git
- 非用户要求不输出多余内容

### 编辑规则
- 编辑文件仅使用 Read 和 Edit 工具，不使用 Python/PowerShell/Bash 修改文件
- Edit 工具使用函数签名等唯一字符串做锚点，避免 tab 缩进匹配问题

### Git 提交规范
- `feat:` 新功能 | `fix:` 修复 | `refactor:` 重构 | `style:` 样式 | `perf:` 性能 | `chore:` 构建/工具/配置