Skip to content

CLAUDE.md

Latest commit

 

History

History
81 lines (53 loc) · 3.46 KB

CLAUDE.md

File metadata and controls

81 lines (53 loc) · 3.46 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Firefly is a feature-rich static blog theme built on Astro 6 with Svelte 5 for interactive components. It's a fork of Fuwari extended with extensive features. Primary language is Chinese (Simplified) with i18n for en, zh_TW, ja, ru.

Commands

Command Purpose
pnpm dev Dev server at localhost:4321
pnpm build Production build (icons → LQIPs → Astro build → Pagefind indexing)
pnpm preview Preview production build
pnpm check astro check for type/error checking
pnpm type-check tsc --noEmit --isolatedDeclarations
pnpm lint Biome lint + auto-fix
pnpm format Biome format
pnpm new-post <filename> Scaffold a new blog post

Package manager is pnpm (enforced). Node.js >= 22 required.

Architecture

Astro + Svelte Hybrid

  • .astro components for static content and layouts
  • .svelte components for interactive UI (search, settings, pagination, archive) — mounted with client:load or client:visible
  • Swup.js handles SPA-like page transitions with multiple container targets

Configuration-Driven

All features are toggled/configured via TypeScript files in src/config/, exported through the barrel at src/config/index.ts. Key configs:

  • siteConfig.ts — core site settings, theme, pagination
  • sidebarConfig.ts — sidebar layout (left/right/both, widget ordering)
  • commentConfig.ts, analyticsConfig.ts, fontConfig.ts, etc.

Layout System

  • Layout.astro — base HTML shell (head, body, theme init, analytics, Swup hooks)
  • MainGridLayout.astro — full page grid with sidebar(s), navbar, wallpaper, footer

Content Collections

Defined in src/content.config.ts:

  • posts — blog posts (.md/.mdx) with frontmatter: title, published, tags, category, draft, pinned, password, comment, etc.
  • spec — special pages (about, guestbook)

Key Directories

  • src/components/ — organized by domain: analytics/, comment/, common/, controls/, features/, layout/, misc/, pages/, widget/
  • src/plugins/ — 15 custom remark/rehype plugins (Mermaid, PlantUML, KaTeX, GitHub cards, reading time, etc.)
  • src/i18n/ — translation keys in i18nKey.ts, language files in languages/*.ts, lookup via translation.ts
  • src/utils/ — content sorting, crypto (encrypted posts), date formatting, image processing/LQIP, TOC generation
  • src/pages/ — Astro file-based routing
  • scripts/ — build-time utilities (generate-icons.js, generate-lqips.ts, new-post.js)

Path Aliases (tsconfig.json)

@components/*, @assets/*, @constants/*, @utils/*, @i18n/*, @layouts/* → ./src/<dir>/*; @/* → ./src/*

Code Style

  • Biome enforces: tab indentation, double quotes, recommended lint rules
  • Relaxed rules for .svelte/.astro files (useConst off, noUnusedVariables off)
  • Commit convention: Conventional Commits (feat:, fix:, chore:, etc.)

Build Pipeline

Multi-step: scripts/generate-icons.js → scripts/generate-lqips.ts → astro build → pagefind --site dist

Icons/LQIP data are generated into src/constants/ and committed. Regenerate with pnpm icons or pnpm lqips.

Deployment

  • Vercel (default, vercel.json)
  • Cloudflare Workers (wrangler.jsonc, set CF_WORKERS env var)
  • Static output to dist/