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

   git clone <repository-url>
   cd astro-template
   

2. Install dependencies

   pnpm install
   

3. Initialize your template

   node init-template.js
   

   Follow the prompts to personalize with your information.

4. Start development server

   pnpm dev
   

   Open 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 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/:

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

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

Deployment

pnpm deploy           # Build and deploy to Cloudflare Pages

Utilities

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

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

   pnpm build
   

2. Deploy

   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

   pnpm commit
   

See src/utils/README.md for details.

Image Optimization

Convert images to AVIF format for optimal performance:

# 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
• UI Library: React 19
• Styling: Tailwind CSS 4
• Deployment: Cloudflare Pages
• 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 for details.

Support

• Documentation
• Astro Docs
• Cloudflare Pages Docs

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!