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

# 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:

---
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

4.3 KiB Raw Permalink Blame History