mirror of
https://github.com/Ad-closeNN/blog-fuwari.git
synced 2026-05-31 01:20:06 -04:00
Ad-closeNN
102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
# AGENTS.md
|
||
|
||
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
基于 [Fuwari](https://github.com/saicaca/fuwari) 的静态博客，使用 Astro 6.1 + TailwindCSS 3.4 + Svelte 5。
|
||
|
||
- **包管理器**: pnpm 9（`preinstall` hook 强制只允许 pnpm）
|
||
- **语言**: TypeScript (strict)
|
||
- **代码规范**: Biome（同时负责 format 和 lint），无 ESLint/Prettier
|
||
- **部署**: Cloudflare Pages（见 `wrangler.toml`）
|
||
|
||
## 常用命令
|
||
|
||
| 命令 | 用途 |
|
||
|---|---|
|
||
| `pnpm dev` | 启动本地开发服务器 (`localhost:4321`) |
|
||
| `pnpm build` | 构建生产版本到 `./dist/` 并运行 Pagefind 索引 |
|
||
| `pnpm preview` | 本地预览构建产物 |
|
||
| `pnpm check` | 运行 Astro 类型检查 |
|
||
| `pnpm type-check` | 运行 TypeScript 类型检查 (`tsc --noEmit`) |
|
||
| `pnpm format` | Biome 格式化 `./src` |
|
||
| `pnpm lint` | Biome 检查和修复 `./src` |
|
||
| `pnpm new-post <filename>` | 在 `src/content/posts/` 创建新文章 Markdown |
|
||
| `pnpm astro` | 直接调用 Astro CLI |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── config.ts # 站点主配置（标题、导航、个人资料、许可证等）
|
||
├── content.config.ts # Astro Content Collections 定义（posts + spec）
|
||
├── content/
|
||
│ ├── posts/ # 博客文章（.md / .mdx），通过文件系统集合加载
|
||
│ └── spec/ # 特殊页面集合
|
||
├── components/
|
||
│ ├── widget/ # 侧边栏组件（Profile, TOC, Tags, Categories 等）
|
||
│ ├── control/ # 交互控件（BackToTop, Pagination, ButtonLink 等）
|
||
│ ├── misc/ # 杂项（ImageWrapper, License, Markdown）
|
||
│ └── *.astro/*.svelte # 页面级组件（Navbar, Footer, Search, PostPage 等）
|
||
├── pages/
|
||
│ ├── [...page].astro # 首页分页路由
|
||
│ ├── posts/[...slug].astro # 文章详情页
|
||
│ ├── archive.astro # 归档页
|
||
│ ├── about.astro # 关于页
|
||
│ ├── friends.astro # 友链页
|
||
│ ├── rss.xml.ts # RSS 生成
|
||
│ └── robots.txt.ts # robots.txt
|
||
├── layouts/
|
||
│ ├── Layout.astro # 根布局（SEO、主题、Umami 分析、PhotoSwipe）
|
||
│ └── MainGridLayout.astro # 主网格布局（导航栏、Banner、侧边栏、TOC）
|
||
├── plugins/ # Remark/Rehype 插件 + Expressive Code 插件
|
||
├── i18n/ # 多语言翻译（en, zh_CN, ja, ko 等）
|
||
├── utils/ # 工具函数（content-utils, date-utils, url-utils, setting-utils）
|
||
├── types/ # TypeScript 类型定义
|
||
├── constants/ # 常量（分页大小、主题模式、Banner 高度等）
|
||
└── styles/ # CSS 文件（main.css, markdown.css, scrollbar.css 等）
|
||
```
|
||
|
||
## 关键架构信息
|
||
|
||
### 内容管理
|
||
- 文章以 Markdown/MDX 格式存储在 `src/content/posts/`
|
||
- 使用 Astro Content Collections 加载，schema 在 `content.config.ts` 中定义
|
||
- 文章 frontmatter 包含: `title`, `published`, `description`, `image`, `tags`, `category`, `draft`, `lang`, `showcover`, `customcover` 等
|
||
|
||
### 路由
|
||
- `[...page].astro` — 首页分页
|
||
- `posts/[...slug].astro` — 文章详情页，生成 JSON-LD 结构化数据
|
||
- `archive.astro` — 归档，tags，categories
|
||
- 自定义页面: `about.astro`, `friends.astro`
|
||
|
||
### 路径别名（tsconfig 配置）
|
||
- `@/*` → `src/*`，`@components/*` → `src/components/*`，`@assets/*` → `src/assets/*`
|
||
- `@utils/*` → `src/utils/*`，`@i18n/*` → `src/i18n/*`
|
||
- `@layouts/*` → `src/layouts/*`，`@constants/*` → `src/constants/*`
|
||
|
||
### 页面过渡
|
||
- 使用 Swup 实现 SPA 风格页面过渡
|
||
- 支持自定义滚动条 (`OverlayScrollbars`)，图片点击放大 (`PhotoSwipe`)
|
||
|
||
### Markdown 扩展
|
||
- GitHub Admonitions (note, tip, important, caution, warning)
|
||
- GitHub 仓库卡片，数学公式 (KaTeX)
|
||
- 扩展代码块 (Expressive Code) 支持折叠、行号、复制按钮、语言徽章
|
||
- 自动标题锚点链接
|
||
|
||
### 外部服务
|
||
- **分析**: Umami（自建）+ Google Analytics
|
||
- **评论**: Giscus（基于 GitHub Discussions）
|
||
- **搜索**: Pagefind（构建时生成搜索索引）
|
||
- **统计**: 通过 Umami API 获取文章浏览量
|
||
|
||
## 注意事项
|
||
|
||
- `src/config.ts` 是站点配置中心
|
||
- 构建会先运行 `astro build`，然后执行 `pagefind --site dist` 生成搜索索引
|
||
- Biome 不处理 CSS 文件（在 `biome.json` 中排除）
|
||
- Svelte 组件使用 Svelte 5 语法
|
||
- 主题色基于 CSS 变量 `--hue` 动态计算
|