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

# 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

# Start development server (http://localhost:3000)
pnpm dev

# Build for production
pnpm build

# Preview production build locally
pnpm preview

Deployment

# Deploy to Cloudflare Pages
pnpm deploy

Environment Variables

Create a .env.local file based on .env.example:

# 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

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

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

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

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

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

pnpm commit

Requires OpenRouter API key in src/utils/.env

Cloudflare Type Generation

Generate TypeScript types for Cloudflare Workers:

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

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

PUBLIC_SITE_URL=https://summitpaintingcolorado.com
PUBLIC_SITE_NAME=Summit Painting & Handyman

Cloudflare Configuration

Key settings in wrangler.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

# 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