Add image optimization script

Also added dev requirements file that includes Pillow required for the script to run.

Author: mrbiggred

AGENTS.md

@@ -7,7 +7,7 @@ Weekly Dev Chat website — MkDocs Material static site. Read `mkdocs.yml` and r
 - Posts are for Tuesdays (the weekly chat day). Use next Tuesday's date unless told otherwise.
 - End post body with this paragraph (before the image):
   `Everyone and anyone is welcome to [join](https://weeklydevchat.com/join/) as long as you are kind, supportive, and respectful of others. Zoom link will be posted at 12pm MDT.`
-- Place images in the same directory as the post's `index.md`.
+- Place images in the same directory as the post's `index.md`. Run `python3 scripts/optimize_image.py <image>` to convert to WebP and resize for the web.
 - Use `./create_post.sh` to scaffold a new post (calculates next Tuesday automatically).
 - **Multiple posts on the same date:** If a date folder already has an `index.md`, prefix the filename with a number and dash (e.g., `0-index.md`). The newest/latest post should use the lowest number so it appears first on the homepage. The original `index.md` keeps its name.
 

README.md

@@ -118,6 +118,43 @@ These scripts will:
 
 4. Add any images to the same directory as the post
 
+5. **Optimize images** for the web before committing (see [Optimizing Images](#optimizing-images) below)
+
+### Optimizing Images
+
+After adding an image to a post, run the optimization script to convert it to WebP and resize it for the web:
+
+```bash
+python3 scripts/optimize_image.py docs/posts/YYYY/MM/DD/your_image.png
+```
+
+This will create an optimized `.webp` file alongside the original. Update your post's markdown to reference the new `.webp` file, then delete the original if no longer needed.
+
+**Options:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--quality` | 80 | WebP quality (1–100) |
+| `--max-width` | 1200 | Max width in pixels (won't upscale) |
+
+**Examples:**
+
+```bash
+# Optimize a single image with defaults
+python3 scripts/optimize_image.py docs/posts/2026/04/14/photo.png
+
+# Batch optimize multiple images
+python3 scripts/optimize_image.py docs/posts/2026/04/14/*.png docs/posts/2026/04/14/*.jpg
+
+# Custom quality and max width
+python3 scripts/optimize_image.py --quality 90 --max-width 1600 image.jpeg
+```
+
+> **Note:** This script requires [Pillow](https://pillow.readthedocs.io/). Install dev dependencies with:
+> ```bash
+> pip install -r requirements-dev.txt
+> ```
+
 ### Categories and Tags
 
 Categories are broad topic groupings and tags are specific topic labels for filtering. **Please use existing categories and tags when possible** to keep the taxonomy consistent. New ones can be added when truly needed.
@@ -145,8 +182,11 @@ This script requires `pyyaml`, which is included in `requirements.txt`. It is al
 ├── docker-compose.yml         # Docker development environment
 ├── create_post.sh             # Bash script to create blog posts
 ├── create_post.ps1            # PowerShell script to create blog posts
+├── requirements-dev.in         # Dev-only dependency pins (e.g. Pillow)
+├── requirements-dev.txt        # Compiled dev dependencies
 ├── scripts/
-│   └── find_tags_categories.py # List all existing tags and categories
+│   ├── find_tags_categories.py # List all existing tags and categories
+│   └── optimize_image.py       # Optimize images for the web (PNG/JPEG → WebP)
 ├── .github/
 │   ├── dependabot.yml         # Dependabot configuration
 │   └── workflows/
@@ -176,6 +216,9 @@ mkdocs serve -a 0.0.0.0:8000   # Start server accessible on network
 mkdocs build                    # Build static site to site/ directory
 mkdocs build --clean            # Clean build
 
+# Optimize an image for the web
+python3 scripts/optimize_image.py docs/posts/YYYY/MM/DD/image.png
+
 # Help
 mkdocs -h                       # Show help
 

requirements-dev.in

@@ -0,0 +1,4 @@
+# Dev-only dependencies (not needed for production builds)
+# uv pip compile requirements-dev.in --output-file requirements-dev.txt
+
+Pillow>=10.0.0

requirements-dev.txt

@@ -0,0 +1,8 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+#    pip-compile --output-file=requirements-dev.txt requirements-dev.in
+#
+pillow==11.3.0
+    # via -r requirements-dev.in

scripts/optimize_image.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+Optimize images for the Weekly Dev Chat website.
+
+Converts images to WebP format, resizes to a max width, and reports savings.
+The original file is preserved; the optimized WebP is written alongside it.
+
+Usage:
+    python scripts/optimize_image.py image1.png image2.jpg
+    python scripts/optimize_image.py --quality 85 --max-width 1600 image.png
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError:
+    print(
+        "Error: Pillow is not installed.\n"
+        "Install dev dependencies with:\n"
+        "  pip install -r requirements-dev.txt\n"
+        "Or install Pillow directly:\n"
+        "  pip install Pillow",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+SUPPORTED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tiff", ".tif", ".webp"}
+
+
+def optimize_image(input_path: Path, *, quality: int, max_width: int) -> Path | None:
+    """Optimize a single image. Returns the output path, or None on error."""
+    if input_path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        print(f"  Skipping {input_path.name}: unsupported format")
+        return None
+
+    try:
+        img = Image.open(input_path)
+    except Exception as e:
+        print(f"  Error opening {input_path.name}: {e}", file=sys.stderr)
+        return None
+
+    # Convert palette/RGBA images appropriately for WebP
+    if img.mode in ("P", "PA"):
+        img = img.convert("RGBA")
+    elif img.mode not in ("RGB", "RGBA"):
+        img = img.convert("RGB")
+
+    # Resize if wider than max_width, preserving aspect ratio
+    if img.width > max_width:
+        ratio = max_width / img.width
+        new_height = round(img.height * ratio)
+        img = img.resize((max_width, new_height), Image.LANCZOS)
+
+    output_path = input_path.with_suffix(".webp")
+    img.save(output_path, "WEBP", quality=quality)
+
+    original_size = input_path.stat().st_size
+    optimized_size = output_path.stat().st_size
+    change_pct = (optimized_size / original_size - 1) * 100 if original_size > 0 else 0
+
+    print(f"  {input_path.name}")
+    print(f"    {original_size:,} bytes → {optimized_size:,} bytes ({change_pct:+.1f}%)")
+    print(f"    Saved to {output_path.name} ({img.width}x{img.height})")
+
+    return output_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Optimize images for the Weekly Dev Chat website.",
+    )
+    parser.add_argument(
+        "images",
+        nargs="+",
+        type=Path,
+        help="One or more image file paths to optimize.",
+    )
+    parser.add_argument(
+        "--quality",
+        type=int,
+        default=80,
+        help="WebP quality (1-100, default: 80).",
+    )
+    parser.add_argument(
+        "--max-width",
+        type=int,
+        default=1200,
+        help="Max image width in pixels (default: 1200). Images smaller than this are not upscaled.",
+    )
+    args = parser.parse_args()
+
+    successes = 0
+    failures = 0
+
+    for image_path in args.images:
+        if not image_path.is_file():
+            print(f"  Warning: {image_path} not found, skipping.", file=sys.stderr)
+            failures += 1
+            continue
+
+        result = optimize_image(image_path, quality=args.quality, max_width=args.max_width)
+        if result:
+            successes += 1
+        else:
+            failures += 1
+
+    print(f"\nDone: {successes} optimized, {failures} skipped/failed.")
+    sys.exit(1 if failures > 0 and successes == 0 else 0)
+
+
+if __name__ == "__main__":
+    main()