meowrain
7b7e32ddd4
Some checks failed
Clean ESA Versions on Main / clean-esa-versions (push) Has been cancelled
137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Fuwari** is a personal blog theme built with Astro 5.7, customized for AcoFork. It's a static site generator focused on technical blogging with Chinese language support.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Install dependencies (uses pnpm)
|
|
pnpm install
|
|
|
|
# Development server
|
|
pnpm dev # or pnpm start
|
|
|
|
# Build for production
|
|
pnpm build
|
|
|
|
# Preview production build
|
|
pnpm preview
|
|
|
|
# Type checking
|
|
pnpm type-check
|
|
|
|
# Create new blog post (creates file in src/content/posts/)
|
|
pnpm new-post <title>
|
|
|
|
# Clean unused images from src/content/assets/
|
|
pnpm clean
|
|
|
|
# Format code (uses Biome)
|
|
pnpm format
|
|
|
|
# Lint and fix code (uses Biome)
|
|
pnpm lint
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Framework & Build System
|
|
- **Astro 5.7** - Static site generator with component islands architecture
|
|
- **Vite** - Build tool (configured via astro.config.mjs)
|
|
- **Output**: Static HTML/CSS/JS to `dist/` directory
|
|
|
|
### Styling Architecture
|
|
- **Tailwind CSS** - Utility-first CSS with Nesting plugin
|
|
- **Stylus** - Preprocessor for global styles and CSS variables
|
|
- **Theme System**: HSL-based color system with configurable hue in `src/config.ts`
|
|
- Uses CSS custom properties defined in `src/styles/variables.styl`
|
|
- Dark/light mode toggle via `data-theme` attribute
|
|
|
|
### Component Architecture
|
|
- **Svelte 5** - Interactive components (`.svelte` files in `src/components/`)
|
|
- **Astro components** - Static components (`.astro` files)
|
|
- **Layout hierarchy**: `Layout.astro` (root) → page-specific layouts
|
|
|
|
### Content System
|
|
- **Blog posts**: `src/content/posts/*.md` with frontmatter schema validation
|
|
- **Assets**: `src/content/assets/` for images/media
|
|
- **Content collections**: Defined in Astro config with TypeScript schemas
|
|
|
|
### Plugin System (src/plugins/)
|
|
Custom remark/rehype plugins for Markdown processing:
|
|
- `remark-reading-time.mjs` - Calculates reading time
|
|
- `remark-excerpt.js` - Generates post excerpts
|
|
- `remark-directive-rehype.js` - Parses custom directives
|
|
- `rehype-component-admonition.mjs` - GitHub-style callouts (note, tip, warning, etc.)
|
|
- `rehype-component-github-card.mjs` - GitHub repo embedding
|
|
- `rehype-image-fallback.mjs` - Image fallback on failure
|
|
- `expressive-code/custom-copy-button.ts` - Custom code block copy button
|
|
|
|
## Configuration Files
|
|
|
|
- **`src/config.ts`** - Main site configuration
|
|
- Site metadata (title, description, lang)
|
|
- Theme colors (hue, dark mode)
|
|
- Navigation links
|
|
- Profile info
|
|
- Banner/background settings
|
|
- License, analytics, edit links
|
|
|
|
- **`astro.config.mjs`** - Build configuration
|
|
- Integrations (Tailwind, Svelte, Swup, Sitemap, Icon)
|
|
- Markdown remark/rehype plugins pipeline
|
|
- Expressive Code settings
|
|
- Redirects
|
|
- Image service (passthrough mode)
|
|
|
|
- **`tailwind.config.cjs`** - Tailwind configuration
|
|
- Dark mode (`class` strategy)
|
|
- Typography plugin
|
|
- Font family extensions
|
|
|
|
## Key Integrations
|
|
|
|
- **Swup** - Page transitions with SPA-like navigation (configured containers: `main`, `#toc`)
|
|
- **astro-icon** - Icon system with multiple icon sets (FontAwesome, Simple Icons, Material Symbols)
|
|
- **@astrojs/sitemap** - Automatic sitemap generation
|
|
- **Expressive Code** - Code highlighting with GitHub dark theme, collapsible sections, line numbers
|
|
|
|
## Code Quality
|
|
|
|
- **Biome** - Primary linter and formatter (replaces ESLint/Prettier)
|
|
- **TypeScript** - Strict mode enabled, path aliases configured
|
|
- **Type checking**: `pnpm type-check` uses `tsc --noEmit --isolatedDeclarations`
|
|
|
|
## Content Frontmatter Schema
|
|
|
|
Posts use this frontmatter format:
|
|
```yaml
|
|
---
|
|
title: Post Title
|
|
published: 2024-01-01T12:00:00
|
|
description: Post description
|
|
image: ./cover.jpg # Relative to post
|
|
tags: [tag1, tag2]
|
|
category: Category
|
|
draft: false
|
|
lang: zh_CN # Optional, overrides site default
|
|
---
|
|
```
|
|
|
|
## Custom Markdown Features
|
|
|
|
- **GitHub Admonitions**: `> [!NOTE]`, `> [!WARNING]`, etc.
|
|
- **Math**: KaTeX support via `$...$` (inline) and `$$...$$` (block)
|
|
- **Custom directives**: `:::github[repo](url)` for repo cards
|
|
- **Auto TOC**: Generated from headings (configurable depth in `siteConfig.toc.depth`)
|
|
|
|
## Deployment
|
|
|
|
- **Static site**: Builds to `dist/` directory
|
|
- **CI/CD**: GitHub Actions for Alibaba Cloud ESA deployment
|
|
- **Redirects**: Configured in `astro.config.mjs` redirects section
|