astro-template/CLAUDE.md

# CLAUDE.md

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

## Development Commands

### Core Development
```bash
pnpm dev              # Run development server
pnpm build            # Build the project
pnpm preview          # Build and preview with Wrangler
pnpm deploy           # Build and deploy to Cloudflare Pages
```

### Utilities
```bash
# Git commit message automation
pnpm commit                        # Interactive: review, accept/edit, optionally push

# Image conversion to AVIF format
pnpm run convert:avif:all          # Convert all images
pnpm run convert:avif:jpeg         # Convert JPEG only
pnpm run convert:avif:png          # Convert PNG only

# Cloudflare types generation
pnpm cf-typegen                    # Generate Cloudflare types for TypeScript

# Template initialization
node init-template.js              # Interactive setup wizard
node init-template.js --config     # Use template.config.json
```

## Repository Change Documentation

**MANDATORY**: Whenever making any change to the repository (implementations, bug fixes, refactoring, etc.), you MUST update `dev/continuity.md` with:
- Details of the changes made
- Next steps or follow-up actions required
- Any context or decisions that should be preserved for future work

This ensures continuity of work and helps maintain context across development sessions.

## High-Level Architecture

This is an Astro-based template built for portfolio and blog sites deployed on Cloudflare Pages. The architecture follows a content-driven approach with three distinct layers:

### 1. Content Layer (`src/content/**`)
Content is managed via Astro's Content Collections API with schema validation defined in `src/content.config.ts`:

- **`blog/`** - Blog posts as MDX files
  - Schema: title, description, pubDate, updatedDate (optional), heroImage (optional), featured (boolean), category, tags
  - Posts are sorted by pubDate (newest first)

- **`sections/`** - Homepage section content (hero, experience, skills, featured-project)
  - Each section has a custom schema for its specific data needs
  - Experience entries include systemId, status, dates, company, role, tags, description, achievements, link
  - Skills entries include id, domain, tools, proficiency

- **`pages/`** - Page-specific content (contact form configuration)
  - Includes form labels, social links, subject options

### 2. Component Layer
Components are organized by purpose:

- **Core UI**: `BlogCard`, `FormattedDate`, `Navigation`, `Footer`, `GridOverlay`
- **Blog-specific**: `BlogFilters`, `ReadingProgress`, `TableOfContents`, `PostNavigation`, `RelatedPosts`
- **Section components**: `Hero`, `Experience`, `Skills`, `FeaturedProject`

### 3. Page & Layout Layer
- **Layouts**: `BaseLayout` (shared structure), `BlogPost` (blog template)
- **Routes**: Static routes in `src/pages/` with dynamic blog routes via `[...slug].astro`

## Data Flow Patterns

### Blog Index (`src/pages/blog/index.astro`)
1. Fetches all posts via `getCollection('blog')`
2. Sorts by pubDate (newest first)
3. Identifies featured post (first with `featured: true` or fallback to latest)
4. Renders featured hero + filterable grid of all posts
5. Extracts unique categories for filter UI

### Individual Blog Posts (`src/pages/blog/[...slug].astro`)
1. Uses `getStaticPaths()` to generate all blog post routes
2. For each post, calculates:
   - Previous/next posts (by date)
   - Related posts (matching category or shared tags, limited to 3)
   - Reading time (based on word count, 200 wpm)
3. Passes everything to `BlogPost` layout which handles headings, navigation, related posts

### Content Collections
All content follows the schema validation pattern:
```
MDX file → src/content.config.ts schema → getCollection() → Component props
```

## Key Technical Patterns

### Image Handling
- Assets in `src/assets/` are processed by Astro (use relative paths in frontmatter)
- Static files in `public/media/` are served as-is (use absolute paths like `/media/file.mp4`)
- AVIF conversion utility available for optimization

### Deployment
- Cloudflare Pages adapter configured in `astro.config.mjs`
- Image service set to "compile" mode
- Platform proxy enabled for development

## Blog Post Creation Workflow

1. Create `.mdx` file in `src/content/blog/` (filename becomes URL slug)
2. Add required frontmatter: title, description, pubDate
3. Optionally add: heroImage, featured, category, tags
4. Write content using Markdown/MDX with embedded JSX/HTML
5. Images can reference `src/assets/` (relative) or `public/media/` (absolute)

## Utility Scripts

- **`init-template.js`** - Template initialization wizard (interactive and config modes)
- **`src/utils/convert-to-avif.js`** - Converts images to AVIF format with quality options
- **`src/utils/git-commit.js`** - AI-powered commit message generation using OpenRouter API

## Template Features

This template is designed to be easily customizable and includes:

- **Content Collections** - Type-safe MDX content with schema validation
- **Design System** - Comprehensive design documentation in `dev/design.json`
- **SEO Optimization** - Structured data, meta tags, Open Graph support
- **Image Optimization** - AVIF conversion utility for modern image formats
- **AI Tooling** - Optional AI-powered git commit messages
- **Deployment Ready** - Pre-configured for Cloudflare Pages