Image Optimization Scripts

Modular PowerShell scripts for optimizing website images to meet performance standards defined in CLAUDE.md.

Performance Standards

All scripts validate against these targets from CLAUDE.md:

Scripts Overview

1. optimize-images.ps1

Purpose: Convert images to WebP format with dimension extraction and performance validation.

Features:

Usage:

# Convert large images (>50KB)
.\scripts\optimize-images.ps1

# Convert all images
.\scripts\optimize-images.ps1 -ConvertAll

# Custom quality settings
.\scripts\optimize-images.ps1 -Quality 80 -BackgroundQuality 50

Output:

Requirements:

2. update-image-references.ps1

Purpose: Update HTML and Markdown files to use WebP images with proper dimensions and loading attributes.

Features:

Usage:

# Preview changes (no modifications)
.\scripts\update-image-references.ps1 -WhatIf

# Update with dimensions only
.\scripts\update-image-references.ps1

# Update with full performance attributes
.\scripts\update-image-references.ps1 -AddLoadingAttributes -AddFetchPriority

What it updates:

3. generate-responsive-sizes.ps1

Purpose: Create multiple size variants for responsive srcset support.

Features:

Usage:

# Generate responsive sizes for all image types
.\scripts\generate-responsive-sizes.ps1

# Generate only for specific types
.\scripts\generate-responsive-sizes.ps1 -ImageTypes Hero,Screenshot

# Custom quality
.\scripts\generate-responsive-sizes.ps1 -Quality 80

Output:

Note: After generating, manually update HTML to use srcset:

<img src="hero-1920w.webp"
     srcset="hero-640w.webp 640w, hero-1280w.webp 1280w, hero-1920w.webp 1920w"
     sizes="(max-width: 640px) 640px, (max-width: 1280px) 1280px, 1920px"
     width="1920" height="1080"
     loading="eager"
     fetchpriority="high"
     alt="Hero background">

4. validate-image-performance.ps1

Purpose: Comprehensive validation of all images against performance standards.

Features:

Usage:

# Validate and show results
.\scripts\validate-image-performance.ps1

# Generate HTML report
.\scripts\validate-image-performance.ps1 -GenerateReport

# Fail on warnings (for CI/CD)
.\scripts\validate-image-performance.ps1 -FailOnWarnings

Output:

Use in CI/CD:

- name: Validate image performance
  run: .\scripts\validate-image-performance.ps1 -FailOnWarnings

Complete Workflow

Integrated Build Command

The easiest way to run the complete optimization workflow:

.\build.ps1 -Mode optimize-images

This runs all four scripts in sequence:

  1. Optimize images to WebP
  2. Update references with dimensions
  3. Generate responsive sizes
  4. Validate performance compliance

Manual Step-by-Step

If you prefer to run scripts individually:

# Step 1: Optimize images
.\scripts\optimize-images.ps1 -ConvertAll

# Step 2: Update references
.\scripts\update-image-references.ps1 -AddLoadingAttributes -AddFetchPriority

# Step 3: Generate responsive sizes (optional)
.\scripts\generate-responsive-sizes.ps1 -ImageTypes Hero,Screenshot

# Step 4: Validate compliance
.\scripts\validate-image-performance.ps1 -GenerateReport

Quick Validation

To quickly check image compliance without making changes:

.\build.ps1 -Mode validate-images

Common Scenarios

Adding New Images

When adding new images to the site:

  1. Place original images in assets/images/
  2. Run optimization workflow: 
    .\build.ps1 -Mode optimize-images
  3. Review changes in git
  4. Test locally: .\build.ps1
  5. Commit and deploy

Fixing Non-Compliant Images

If validation shows warnings:

  1. Check the report: image-performance-report.html
  2. For size issues: Reduce quality or dimensions in source
  3. For missing dimensions: Run update-image-references.ps1
  4. For wrong format: Ensure images are WebP
  5. Re-validate: .\build.ps1 -Mode validate-images

Pre-Deployment Check

Before deploying to production:

# Validate all images
.\build.ps1 -Mode validate-images

# Run performance benchmarks
.\build.ps1 -Mode benchmark

Performance Impact

Following this workflow ensures:

Troubleshooting

ImageMagick not found:

cwebp not found:

Metadata file not found:

References not updating:

Responsive sizes not generating:

Integration with CI/CD

Add to GitHub Actions workflow:

- name: Validate image performance
  run: |
    .\scripts\validate-image-performance.ps1 -FailOnWarnings
  shell: pwsh

- name: Check for non-compliant images
  if: failure()
  run: |
    Write-Host "Image performance validation failed!"
    Write-Host "Run: .\build.ps1 -Mode optimize-images"
  shell: pwsh

Best Practices

  1. Always run optimization before committing new images
  2. Test locally after optimization to verify images display correctly
  3. Review git changes to ensure references were updated correctly
  4. Run validation before deploying to production
  5. Keep originals in a separate backup location (not in repo)
  6. Document custom sizes if deviating from standards
  7. Update CLAUDE.md if performance targets change

Script Dependencies

optimize-images.ps1
  ├── ImageMagick (identify, resize)
  ├── cwebp (WebP conversion)
  └── Outputs: image-metadata.json

update-image-references.ps1
  ├── Requires: image-metadata.json
  └── Updates: *.html, *.md files

generate-responsive-sizes.ps1
  ├── Requires: image-metadata.json
  ├── ImageMagick (resize)
  ├── cwebp (WebP conversion)
  └── Outputs: *-{width}w.webp files

validate-image-performance.ps1
  ├── ImageMagick (identify)
  └── Outputs: image-performance-report.html (optional)

Future Enhancements

Potential improvements for future versions:

Last Updated: 2025-11-24 Maintained By: Chris Taylor Questions: See CLAUDE.md or open an issue