generated from Nicholai/astro-template
refactor: overhaul project documentation and UI components
- 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
This commit is contained in:
parent
c476385718
commit
8dcd6c09f3
@ -1,10 +0,0 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(ffmpeg:*)",
|
||||
"Bash(ls:*)"
|
||||
],
|
||||
"deny": [],
|
||||
"ask": []
|
||||
}
|
||||
}
|
||||
440
README.md
440
README.md
@ -1,109 +1,427 @@
|
||||
# Astro Template
|
||||
# Summit Painting & Handyman Services
|
||||
|
||||
Minimal Astro development environment with React, Tailwind CSS, and Cloudflare Pages deployment.
|
||||
> **Craftsmanship For Your Home**
|
||||
|
||||
## Stack
|
||||
The official website for Summit Painting & Handyman Services in Colorado Springs. Built with modern web technologies for performance, maintainability, and scalability.
|
||||
|
||||
- **Astro 5** - Static site framework
|
||||
## Technology Stack
|
||||
|
||||
- **Astro 5** - Static site generator with React islands
|
||||
- **React 19** - Interactive components
|
||||
- **Tailwind CSS 4** - Styling
|
||||
- **MDX** - Markdown with JSX
|
||||
- **TypeScript** - Type safety
|
||||
- **Cloudflare Pages** - Deployment
|
||||
- **pnpm** - Package manager
|
||||
- **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
|
||||
|
||||
# Start dev server
|
||||
# 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
|
||||
# Build for production
|
||||
pnpm build
|
||||
|
||||
# Deploy
|
||||
# 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
|
||||
|
||||
```
|
||||
src/
|
||||
├── assets/ # Images (processed by Astro)
|
||||
├── components/ # React/Astro components
|
||||
├── content/ # MDX content collections
|
||||
│ ├── blog/ # Blog posts
|
||||
│ ├── sections/ # Homepage sections
|
||||
│ └── pages/ # Page content
|
||||
├── layouts/ # Page layouts
|
||||
├── pages/ # Routes
|
||||
├── styles/ # Global CSS
|
||||
└── utils/ # Utility scripts
|
||||
|
||||
public/
|
||||
└── media/ # Static assets
|
||||
|
||||
dev/
|
||||
├── design.json # Design system docs
|
||||
└── continuity.md # Development log
|
||||
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
|
||||
```
|
||||
|
||||
## Content Collections
|
||||
## Architecture Overview
|
||||
|
||||
### Blog Posts (`src/content/blog/`)
|
||||
### 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: 'Post Title'
|
||||
description: 'Description'
|
||||
pubDate: 'Dec 27 2024'
|
||||
heroImage: '../../assets/image.avif'
|
||||
featured: true
|
||||
category: 'Category'
|
||||
tags: ['tag1', 'tag2']
|
||||
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']
|
||||
---
|
||||
|
||||
Content here...
|
||||
Your content here...
|
||||
```
|
||||
|
||||
### Sections (`src/content/sections/`)
|
||||
3. Post automatically appears on blog index sorted by date
|
||||
|
||||
- `hero.mdx` - Hero section
|
||||
- `experience.mdx` - Work history
|
||||
- `skills.mdx` - Skills
|
||||
- `featured-project.mdx` - Featured work
|
||||
### Editing Homepage Sections
|
||||
|
||||
See files for schema examples.
|
||||
Edit corresponding MDX files in `src/content/sections/`:
|
||||
- `hero.mdx` - Hero banner content
|
||||
- Experience section
|
||||
- Skills section
|
||||
- Featured project showcase
|
||||
|
||||
## Utilities
|
||||
Changes are immediately reflected on homepage.
|
||||
|
||||
## Utility Scripts
|
||||
|
||||
### Image Optimization
|
||||
|
||||
Convert images to AVIF format for better performance:
|
||||
|
||||
```bash
|
||||
# AI-powered commit messages
|
||||
pnpm commit
|
||||
|
||||
# Convert images to AVIF
|
||||
# Convert all images
|
||||
pnpm convert:avif:all
|
||||
pnpm convert:avif:jpeg
|
||||
pnpm convert:avif:png
|
||||
|
||||
# Generate Cloudflare types
|
||||
# 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
|
||||
```
|
||||
|
||||
## Configuration
|
||||
## Deployment Guide
|
||||
|
||||
- `src/consts.ts` - Site constants
|
||||
- `astro.config.mjs` - Astro config
|
||||
- `wrangler.jsonc` - Cloudflare config
|
||||
- `dev/design.json` - Design system
|
||||
### Prerequisites
|
||||
|
||||
## Development
|
||||
- Cloudflare Pages project configured
|
||||
- `wrangler.json` with proper configuration
|
||||
|
||||
See `CLAUDE.md` for detailed architecture and development patterns.
|
||||
### 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
|
||||
|
||||
@ -50,3 +50,4 @@ const { items, speed = 20, reverse = false } = Astro.props;
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
|
||||
@ -20,3 +20,4 @@ const { title, subtitle, centered = false, class: className = "" } = Astro.props
|
||||
)}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
@ -232,3 +232,4 @@ const serviceAreas = [
|
||||
<Footer />
|
||||
</Layout>
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user