astro-template/README.md

# Astro Portfolio & Blog Template

A modern, high-performance portfolio and blog template built with **Astro 5**, **React 19**, and **Tailwind CSS 4**. Features an industrial dark design system, MDX blog support, and deployment-ready for Cloudflare Pages.

## Features

### Content Management
- **Type-Safe Content Collections** - Schema validation with Astro's Content Collections API
- **MDX Blog Support** - Write posts in Markdown with embedded React components
- **Flexible Taxonomies** - Organize content with categories and tags
- **Featured Posts** - Highlight your best work
- **Related Posts** - Automatic suggestions based on content similarity
- **Reading Time Calculation** - Automatic based on word count

### Design & UX
- **Industrial Dark Design System** - Professional, modern aesthetic
- **Fully Responsive** - Mobile-first design approach
- **Custom Components** - Blog cards, filters, navigation, table of contents
- **Reading Progress Indicator** - Visual progress bar for long-form content
- **Theme Toggle** - Dark/light mode support
- **Grid Overlay** - Optional design grid for development

### Performance & SEO
- **Lightning Fast** - Built with Astro for optimal performance
- **SEO Optimized** - Structured data (JSON-LD), meta tags, Open Graph
- **AVIF Image Support** - Modern image format with conversion utility
- **RSS Feed** - Automatic feed generation
- **Sitemap** - Auto-generated for search engines
- **Cloudflare Pages Ready** - Optimized for edge deployment

### Developer Experience
- **TypeScript** - Full type safety
- **pnpm** - Fast, disk-efficient package manager
- **AI-Powered Git Commits** - Automatic commit message generation
- **AVIF Converter** - Built-in image optimization utility
- **Template Initialization** - Interactive setup script

## Quick Start

### Prerequisites

- **Node.js** 18+
- **pnpm** (recommended) - `npm install -g pnpm`

### Installation

1. **Clone or download this template**
   ```bash
   git clone <repository-url>
   cd astro-template
   ```

2. **Install dependencies**
   ```bash
   pnpm install
   ```

3. **Initialize your template**
   ```bash
   node init-template.js
   ```
   Follow the prompts to personalize with your information.

4. **Start development server**
   ```bash
   pnpm dev
   ```
   Open [http://localhost:4321](http://localhost:4321)

5. **Replace placeholder content**
   - Update images in `src/assets/` and `public/media/`
   - Customize sections in `src/content/sections/`
   - Write your first blog post in `src/content/blog/`

See [SETUP.md](./SETUP.md) for detailed setup instructions.

## Project Structure

```
/
├── public/              # Static assets (served as-is)
│   ├── media/          # Videos, large images
│   └── fonts/          # Web fonts
├── src/
│   ├── assets/         # Optimized images (processed by Astro)
│   ├── components/     # Reusable UI components
│   │   ├── sections/   # Homepage section components
│   │   └── ...
│   ├── content/        # Content collections
│   │   ├── blog/       # Blog posts (MDX)
│   │   ├── sections/   # Homepage sections (MDX)
│   │   └── pages/      # Page-specific content
│   ├── layouts/        # Page layouts
│   ├── pages/          # File-based routing
│   ├── styles/         # Global styles
│   ├── utils/          # Utility scripts
│   └── consts.ts       # Site-wide constants
├── dev/                # Development resources
│   ├── design.json     # Design system documentation
│   └── continuity.md   # Development log
├── template.config.json # Template configuration
└── init-template.js    # Setup script
```

## Content Collections

### Blog Posts

Create MDX files in `src/content/blog/`:

```yaml
---
title: 'Your Post Title'
description: 'SEO description'
pubDate: 'Dec 27 2024'
heroImage: '../../assets/your-image.avif'
featured: true
category: 'Tutorial'
tags: ['Tag1', 'Tag2']
---

Your content here...
```

### Sections

Customize homepage sections in `src/content/sections/`:
- `hero.mdx` - Hero section with headline and bio
- `experience.mdx` - Work history and achievements
- `skills.mdx` - Technical skills and proficiencies
- `featured-project.mdx` - Showcase your best work

## Available Commands

### Development
```bash
pnpm dev              # Start dev server (localhost:4321)
pnpm build            # Build for production
pnpm preview          # Build and preview with Wrangler
```

### Deployment
```bash
pnpm deploy           # Build and deploy to Cloudflare Pages
```

### Utilities
```bash
pnpm commit                        # AI-powered commit messages
pnpm convert:avif:all              # Convert all images to AVIF
pnpm convert:avif:jpeg             # Convert JPEG only
pnpm convert:avif:png              # Convert PNG only
pnpm cf-typegen                    # Generate Cloudflare types
```

### Template Setup
```bash
node init-template.js              # Interactive setup
node init-template.js --config     # Use template.config.json
```

## Customization

### Design System

The design system is documented in `dev/design.json`. Key areas:

- **Colors**: Modify CSS custom properties in `src/styles/global.css`
- **Typography**: Adjust font scales and families
- **Spacing**: Grid system and spacing tokens
- **Components**: Design patterns and component specs

### Configuration Files

- **template.config.json** - Site-wide settings (name, URLs, social links)
- **astro.config.mjs** - Astro configuration
- **wrangler.jsonc** - Cloudflare Pages settings
- **src/consts.ts** - Global constants

### Adding Content

1. **New Blog Post**: Create `.mdx` file in `src/content/blog/`
2. **Update Sections**: Edit files in `src/content/sections/`
3. **Add Images**: Place in `src/assets/` (processed) or `public/media/` (static)
4. **Customize Components**: Modify files in `src/components/`

## Deployment

### Cloudflare Pages (Default)

1. **Build your site**
   ```bash
   pnpm build
   ```

2. **Deploy**
   ```bash
   pnpm deploy
   ```
   Or connect your Git repository to Cloudflare Pages for automatic deployments.

### Other Platforms

This template can be adapted for other platforms:
- **Vercel**: Change adapter to `@astrojs/vercel`
- **Netlify**: Change adapter to `@astrojs/netlify`
- **Static**: Remove adapter for static site generation

## AI-Powered Commit Messages

This template includes an AI commit message generator:

1. **Setup**: Create `src/utils/.env` with your OpenRouter API key
   ```
   OPENROUTER_API_KEY=your_key_here
   ```

2. **Use**: Stage changes and run
   ```bash
   pnpm commit
   ```

See `src/utils/README.md` for details.

## Image Optimization

Convert images to AVIF format for optimal performance:

```bash
# Convert all images
pnpm convert:avif:all

# Convert specific formats
pnpm convert:avif:jpeg
pnpm convert:avif:png
```

The utility processes files in `src/assets/` and `public/media/`.

## Tech Stack

- **Framework**: [Astro 5](https://astro.build)
- **UI Library**: [React 19](https://react.dev)
- **Styling**: [Tailwind CSS 4](https://tailwindcss.com)
- **Deployment**: [Cloudflare Pages](https://pages.cloudflare.com)
- **Content**: MDX with Content Collections
- **Package Manager**: pnpm

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Modern mobile browsers

## Contributing

This is a template repository. Feel free to fork and customize for your needs.

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Support

- [Documentation](./SETUP.md)
- [Astro Docs](https://docs.astro.build)
- [Cloudflare Pages Docs](https://developers.cloudflare.com/pages)

## Credits

Built with modern web technologies and best practices for performance, SEO, and developer experience.

---

**Ready to make it yours?** Run `node init-template.js` to get started!