generated from Nicholai/astro-template
Nicholai
8dcd6c09f3
- Delete hidden fuse file - Rewrite README with new branding, stack, and deployment instructions - Update Marquee and SectionHeading Astro components - Adjust contact page for new layout and content structure
428 lines
11 KiB
Markdown
428 lines
11 KiB
Markdown
# Summit Painting & Handyman Services
|
|
|
|
> **Craftsmanship For Your Home**
|
|
|
|
The official website for Summit Painting & Handyman Services in Colorado Springs. Built with modern web technologies for performance, maintainability, and scalability.
|
|
|
|
## Technology Stack
|
|
|
|
- **Astro 5** - Static site generator with React islands
|
|
- **React 19** - Interactive components
|
|
- **TypeScript** - Type-safe development
|
|
- **Tailwind CSS 4** - Utility-first styling
|
|
- **MDX** - Markdown with embedded JSX
|
|
- **Cloudflare Pages** - Edge-deployed hosting
|
|
- **pnpm** - Fast, space-efficient package manager
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+ and pnpm installed
|
|
- Git for version control
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd summit-painting-handyman
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Copy environment template and configure
|
|
cp .env.example .env.local
|
|
# Edit .env.local with your configuration
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Start development server (http://localhost:3000)
|
|
pnpm dev
|
|
|
|
# Build for production
|
|
pnpm build
|
|
|
|
# Preview production build locally
|
|
pnpm preview
|
|
```
|
|
|
|
### Deployment
|
|
|
|
```bash
|
|
# Deploy to Cloudflare Pages
|
|
pnpm deploy
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Create a `.env.local` file based on `.env.example`:
|
|
|
|
```bash
|
|
# Site Configuration
|
|
PUBLIC_SITE_URL=https://summitpaintingcolorado.com
|
|
PUBLIC_SITE_NAME=Summit Painting & Handyman
|
|
|
|
# Optional: Analytics, Contact Form, etc.
|
|
# Configure as needed for your services
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
summit-painting-handyman/
|
|
├── src/
|
|
│ ├── assets/ # Images and media processed by Astro
|
|
│ ├── components/
|
|
│ │ ├── home/ # Homepage section components
|
|
│ │ │ ├── Hero.astro
|
|
│ │ │ ├── ServiceList.astro
|
|
│ │ │ ├── ServiceArea.astro
|
|
│ │ │ ├── WhyUs.astro
|
|
│ │ │ └── ExpertiseMosaic.astro
|
|
│ │ ├── site/ # Site-wide components
|
|
│ │ │ ├── Navigation.astro
|
|
│ │ │ ├── Footer.astro
|
|
│ │ │ └── GridOverlay.astro
|
|
│ │ └── ui/ # Reusable UI components
|
|
│ │ ├── Button.astro
|
|
│ │ ├── Container.astro
|
|
│ │ ├── Marquee.astro
|
|
│ │ └── SectionHeading.astro
|
|
│ ├── content/ # Content collections with schema validation
|
|
│ │ ├── blog/ # Blog posts (MDX)
|
|
│ │ ├── sections/ # Homepage sections
|
|
│ │ │ ├── hero.mdx
|
|
│ │ │ ├── experience.mdx
|
|
│ │ │ ├── skills.mdx
|
|
│ │ │ └── featured-project.mdx
|
|
│ │ └── pages/ # Page-specific content
|
|
│ │ └── contact.mdx
|
|
│ ├── layouts/ # Page layout templates
|
|
│ │ ├── BaseLayout.astro
|
|
│ │ └── BlogPost.astro
|
|
│ ├── pages/ # File-based routes
|
|
│ │ ├── index.astro
|
|
│ │ ├── contact.astro
|
|
│ │ ├── blog/
|
|
│ │ │ ├── index.astro
|
|
│ │ │ └── [...slug].astro
|
|
│ │ ├── 404.astro
|
|
│ │ ├── privacy.astro
|
|
│ │ └── terms.astro
|
|
│ ├── styles/ # Global CSS
|
|
│ ├── utils/ # Utility scripts and helpers
|
|
│ ├── consts.ts # Site constants and configuration
|
|
│ └── content.config.ts # Content collection schema definitions
|
|
├── public/
|
|
│ ├── fonts/ # Web fonts
|
|
│ └── media/ # Static assets served as-is
|
|
├── dev/
|
|
│ ├── design.json # Complete design system documentation
|
|
│ └── continuity.md # Development change log
|
|
├── astro.config.mjs # Astro configuration
|
|
├── wrangler.jsonc # Cloudflare Pages configuration
|
|
├── tsconfig.json # TypeScript configuration
|
|
├── tailwind.config.js # Tailwind CSS configuration
|
|
└── package.json # Dependencies and scripts
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Content-Driven Design
|
|
|
|
This site uses Astro's content collections for managing structured content:
|
|
|
|
- **Collections** defined in `src/content.config.ts` with TypeScript schema validation
|
|
- **Markdown & MDX** for rich, maintainable content
|
|
- **Type-safe** frontmatter with automatic validation
|
|
|
|
### Homepage Sections
|
|
|
|
The homepage is composed of modular Astro components that pull from MDX content:
|
|
|
|
1. **Hero** (`Hero.astro`) - Main banner with call-to-action
|
|
2. **Service List** (`ServiceList.astro`) - Primary services overview
|
|
3. **Service Areas** (`ServiceArea.astro`) - Geographic coverage
|
|
4. **Why Us** (`WhyUs.astro`) - Value proposition
|
|
5. **Expertise Mosaic** (`ExpertiseMosaic.astro`) - Visual showcase of work
|
|
|
|
### Blog System
|
|
|
|
- **Blog Index** (`src/pages/blog/index.astro`):
|
|
- Fetches all posts with `getCollection('blog')`
|
|
- Sorts by publication date (newest first)
|
|
- Supports featured post highlighting
|
|
- Implements category/tag filtering
|
|
|
|
- **Individual Posts** (`src/pages/blog/[...slug].astro`):
|
|
- Automatic routing from MDX filenames
|
|
- Previous/next post navigation
|
|
- Related posts (same category/tags, max 3)
|
|
- Reading time calculation (200 wpm)
|
|
- Table of contents generation
|
|
|
|
### Routing
|
|
|
|
- **Static routes** in `src/pages/` → URLs
|
|
- **Blog routes** generated dynamically from `src/content/blog/`
|
|
- **Layouts** wrap pages with common structure
|
|
- **404 page** at `src/pages/404.astro`
|
|
|
|
## Design System
|
|
|
|
### Brand Colors
|
|
|
|
```css
|
|
--color-forest: #3A4D39 /* Primary brand color */
|
|
--color-sage: #739072 /* Secondary accent */
|
|
--color-cream: #ECE3CE /* Background/neutrals */
|
|
```
|
|
|
|
### Typography
|
|
|
|
- **Headings**: Playfair Display (serif)
|
|
- Bold, elegant, premium feel
|
|
- Used for hero titles and section headings
|
|
|
|
- **Body**: Plus Jakarta Sans (sans-serif)
|
|
- Modern, legible, friendly
|
|
- Used for copy, navigation, UI
|
|
|
|
### Design Tokens
|
|
|
|
Complete design system reference available in `dev/design.json`:
|
|
- Color palette
|
|
- Typography scales
|
|
- Spacing system
|
|
- Component patterns
|
|
- Interactive states
|
|
|
|
## Image Handling
|
|
|
|
### Processed Images (`src/assets/`)
|
|
|
|
Images placed here are automatically optimized by Astro:
|
|
|
|
```astro
|
|
// Use relative paths
|
|
import heroImage from '../../assets/hero.jpg'
|
|
<img src={heroImage} alt="Hero image" />
|
|
```
|
|
|
|
Benefits:
|
|
- Automatic AVIF conversion
|
|
- Responsive image generation
|
|
- Optimization at build time
|
|
|
|
### Static Media (`public/media/`)
|
|
|
|
For videos, large files, or assets not needing optimization:
|
|
|
|
```astro
|
|
<!-- Use absolute paths -->
|
|
<video src="/media/video.mp4" />
|
|
```
|
|
|
|
## Content Management
|
|
|
|
### Creating Blog Posts
|
|
|
|
1. Create new file in `src/content/blog/` with `.mdx` extension
|
|
2. Include frontmatter with metadata:
|
|
|
|
```yaml
|
|
---
|
|
title: 'Painting Tips for Colorado Homes'
|
|
description: 'Expert advice for high-altitude painting projects'
|
|
pubDate: 'Jan 2 2026'
|
|
heroImage: '../../assets/blog-image.avif'
|
|
featured: false
|
|
category: 'Tips & Guides'
|
|
tags: ['painting', 'colorado', 'diy']
|
|
---
|
|
|
|
Your content here...
|
|
```
|
|
|
|
3. Post automatically appears on blog index sorted by date
|
|
|
|
### Editing Homepage Sections
|
|
|
|
Edit corresponding MDX files in `src/content/sections/`:
|
|
- `hero.mdx` - Hero banner content
|
|
- Experience section
|
|
- Skills section
|
|
- Featured project showcase
|
|
|
|
Changes are immediately reflected on homepage.
|
|
|
|
## Utility Scripts
|
|
|
|
### Image Optimization
|
|
|
|
Convert images to AVIF format for better performance:
|
|
|
|
```bash
|
|
# Convert all images
|
|
pnpm convert:avif:all
|
|
|
|
# Convert only JPEGs
|
|
pnpm convert:avif:jpeg
|
|
|
|
# Convert only PNGs
|
|
pnpm convert:avif:png
|
|
```
|
|
|
|
Utility: `src/utils/convert-to-avif.js`
|
|
|
|
### AI-Powered Commits
|
|
|
|
Generate commit messages using AI:
|
|
|
|
```bash
|
|
pnpm commit
|
|
```
|
|
|
|
Requires OpenRouter API key in `src/utils/.env`
|
|
|
|
### Cloudflare Type Generation
|
|
|
|
Generate TypeScript types for Cloudflare Workers:
|
|
|
|
```bash
|
|
pnpm cf-typegen
|
|
```
|
|
|
|
## Deployment Guide
|
|
|
|
### Prerequisites
|
|
|
|
- Cloudflare Pages project configured
|
|
- `wrangler.json` with proper configuration
|
|
|
|
### Automatic Deployment
|
|
|
|
The site is configured to deploy to Cloudflare Pages:
|
|
|
|
1. **Build**: Astro generates static HTML/CSS/JS in `./dist/`
|
|
2. **Deploy**: Cloudflare Pages serves the built site globally
|
|
3. **Edge Runtime**: Optional server-side functions via Cloudflare Workers
|
|
|
|
### Manual Deployment
|
|
|
|
```bash
|
|
# Build production bundle
|
|
pnpm build
|
|
|
|
# Preview locally before deploying
|
|
pnpm preview
|
|
|
|
# Deploy to Cloudflare Pages
|
|
pnpm deploy
|
|
```
|
|
|
|
### Environment Configuration
|
|
|
|
Set up environment variables in Cloudflare Pages:
|
|
|
|
```bash
|
|
PUBLIC_SITE_URL=https://summitpaintingcolorado.com
|
|
PUBLIC_SITE_NAME=Summit Painting & Handyman
|
|
```
|
|
|
|
### Cloudflare Configuration
|
|
|
|
Key settings in `wrangler.jsonc`:
|
|
|
|
```jsonc
|
|
{
|
|
"name": "summit-painting-and-handyman-services",
|
|
"compatibility_date": "2025-12-05",
|
|
"env": {
|
|
"production": {
|
|
"name": "summit-painting-production"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Making Changes
|
|
|
|
1. Create a feature branch: `git checkout -b feature/your-feature`
|
|
2. Make changes to content or components
|
|
3. Test locally: `pnpm dev`
|
|
4. Commit changes with: `pnpm commit` (or standard `git commit`)
|
|
5. Push to repository
|
|
6. Automatic deployment to Cloudflare Pages on merge to `main`
|
|
|
|
### Documenting Changes
|
|
|
|
Update `dev/continuity.md` when making significant changes:
|
|
|
|
- **What changed** - File modifications and new features
|
|
- **Why** - Reasoning behind decisions
|
|
- **Next steps** - Follow-up tasks or known limitations
|
|
|
|
### Testing Before Deploy
|
|
|
|
```bash
|
|
# Build and test
|
|
pnpm build
|
|
pnpm preview
|
|
|
|
# Check for TypeScript errors
|
|
# Linting/formatting (if configured)
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
### `src/consts.ts`
|
|
Site-wide constants and configuration values
|
|
|
|
### `astro.config.mjs`
|
|
Astro framework configuration:
|
|
- Site URL
|
|
- Integrations (React, MDX, Sitemap, RSS)
|
|
- Image optimization settings
|
|
- Output format and routing
|
|
|
|
### `wrangler.jsonc`
|
|
Cloudflare Pages deployment configuration:
|
|
- Project name
|
|
- Compatibility date
|
|
- Node.js API compatibility
|
|
|
|
### `dev/design.json`
|
|
Complete design system documentation for reference
|
|
|
|
### `CLAUDE.md`
|
|
Development guidance and architecture patterns for Claude AI assistant
|
|
|
|
## Performance Optimization
|
|
|
|
- **Static HTML** - Pre-rendered at build time
|
|
- **AVIF Images** - Modern format with ~25% smaller file sizes
|
|
- **Cloudflare CDN** - Global edge caching
|
|
- **No JavaScript** - Default rendering (React only for interactive sections)
|
|
- **Sitemap & RSS** - Automatic SEO feeds
|
|
|
|
## Support & Maintenance
|
|
|
|
- **Documentation**: See `CLAUDE.md` for development patterns
|
|
- **Design Reference**: Check `dev/design.json` for brand guidelines
|
|
- **Change Log**: Review `dev/continuity.md` for recent updates
|
|
- **Issues**: Address bugs and improvements through Git
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
---
|
|
|
|
**Last Updated**: January 2, 2026
|