8.7 KiB
8.7 KiB
Blog Image Optimization
Optimize article images with automated compression, format conversion (WebP), and reference updates.
Usage
/blog-optimize-images "language/article-slug"
Examples:
/blog-optimize-images "en/nodejs-best-practices"
/blog-optimize-images "fr/microservices-logging"
Note: Provide the language code and article slug (path relative to articles/).
Prerequisites
Required:
- Article exists at
articles/[language]/[slug]/article.md - Images referenced in article (
.png,.jpg,.jpeg,.gif,.bmp,.tiff) - ffmpeg installed (for conversion)
Install ffmpeg:
# macOS
brew install ffmpeg
# Windows (with Chocolatey)
choco install ffmpeg
# Windows (manual)
# Download from: https://ffmpeg.org/download.html
# Ubuntu/Debian
sudo apt-get install ffmpeg
What This Command Does
Delegates to the quality-optimizer subagent (Phase 4) for image optimization:
- Discovers Images: Scans article for image references
- Backs Up Originals: Copies to
images/.backup/(preserves uncompressed) - Converts to WebP: 80% quality, optimized for web
- Updates References: Changes
.png→.webpin article.md - Reports Results: Shows size reduction and file locations
Time: 10-20 minutes (depends on image count/size)
Output: Optimized images in images/, backups in images/.backup/
Instructions
Create a new subagent conversation with the quality-optimizer agent.
Provide the following prompt:
You are optimizing images for a blog article.
**Article Path**: articles/$ARGUMENTS/article.md
Execute ONLY Phase 4 (Image Optimization) from your instructions:
1. **Image Discovery**:
- Scan article for image references
- Extract image paths from markdown: `grep -E '!\[.*\]\(.*\.(png|jpg|jpeg|gif|bmp|tiff)\)' article.md`
- Build list of images to process
2. **Generate Optimization Script** (`/tmp/optimize-images-$$.sh`):
- Create image optimization script in /tmp/
- Include backup logic (copy originals to images/.backup/)
- Include conversion logic (to WebP, 80% quality)
- Include reference update logic (sed replacements in article.md)
- Make script executable
3. **Execute Script**:
- Run the optimization script
- Capture output and errors
- Verify all images processed successfully
4. **Validation**:
- Check all originals backed up to images/.backup/
- Verify all WebP files created in images/
- Confirm article.md references updated
- Calculate total size reduction
**Important**:
- All scripts must be in /tmp/ (never pollute project)
- Backup originals BEFORE conversion
- Use ffmpeg (cross-platform: Windows, macOS, Linux)
- 80% quality for WebP conversion (hardcoded)
- Update ALL image references in article.md
- Report file size reductions
Begin image optimization now.
Expected Output
After completion, verify:
Backup Directory Created:
ls articles/en/my-article/images/.backup/
# screenshot.png (original)
# diagram.png (original)
Optimized Images Created:
ls articles/en/my-article/images/
# screenshot.webp (optimized, 80% quality)
# diagram.webp (optimized, 80% quality)
Article References Updated:
# Before:
# After:
Size Reduction Report:
Optimization Results:
- screenshot.png: 2.4MB → 512KB (79% reduction)
- diagram.png: 1.8MB → 420KB (77% reduction)
Total savings: 3.3MB (78% reduction)
Supported Image Formats
Source Formats (will be converted)
.png- Portable Network Graphics.jpg/.jpeg- JPEG images.gif- Graphics Interchange Format (first frame).bmp- Bitmap images.tiff- Tagged Image File Format
Target Format
.webp- WebP (80% quality, optimized)
Compression Settings
Hardcoded (cannot be changed via command):
- Quality: 80%
- Format: WebP
- Method: ffmpeg (cross-platform)
Why 80%?
- Excellent visual quality
- Significant file size reduction (30-70%)
- Broad browser support
- Optimal for web performance
Image Workflow
1. Add Images to Article
Place originals in .backup/ first:
cp ~/Downloads/screenshot.png articles/en/my-article/images/.backup/
Reference in article (use .backup/ path initially):
2. Run Optimization
/blog-optimize-images "en/my-article"
3. Verify Results
Check backups:
ls articles/en/my-article/images/.backup/
# screenshot.png
Check optimized:
ls articles/en/my-article/images/
# screenshot.webp
Check article updated:
grep "screenshot" articles/en/my-article/article.md
# 
Multi-Language Support
Images are per-language/per-article:
# English article images
/blog-optimize-images "en/my-topic"
# → articles/en/my-topic/images/
# French article images
/blog-optimize-images "fr/my-topic"
# → articles/fr/my-topic/images/
Sharing images across languages:
# In French article, link to English image
Re-Optimization
If you need to re-optimize:
Restore from Backup
# Copy backups back to main images/
cp articles/en/my-article/images/.backup/* articles/en/my-article/images/
# Update article references to use .backup/ again
sed -i '' 's|images/\([^.]*\)\.webp|images/.backup/\1.png|g' articles/en/my-article/article.md
Run Optimization Again
/blog-optimize-images "en/my-article"
Troubleshooting
"ffmpeg not found"
# Install ffmpeg
brew install ffmpeg # macOS
choco install ffmpeg # Windows (Chocolatey)
sudo apt-get install ffmpeg # Linux
# Verify installation
ffmpeg -version
"No images to optimize"
# Check article has image references
grep "!\[" articles/en/my-article/article.md
# Check image files exist
ls articles/en/my-article/images/.backup/
"Images not updating in article"
# Check current references
grep "images/" articles/en/my-article/article.md
# Manually fix if needed
sed -i '' 's|\.png|.webp|g' articles/en/my-article/article.md
"Permission denied"
# Make optimization script executable
chmod +x /tmp/optimize-images-*.sh
# Or run agent again (it recreates script)
Performance Tips
Before Optimization
- Use descriptive names:
architecture-diagram.pngnotimg1.png - Keep high quality: Optimization preserves visual quality
- Remove unused images: Delete unreferenced images first
After Optimization
- Verify backups exist: Check
.backup/directory - Test image loading: Preview article to ensure images load
- Monitor file sizes: Typical reduction 30-70%
- Commit both: Commit
.backup/and optimized images (or just optimized)
Integration with Workflows
New Article with Images
# 1. Create article
/blog-marketing "en/my-topic"
# 2. Add images to .backup/
cp ~/images/*.png articles/en/my-topic/images/.backup/
# 3. Reference in article.md
# 
# 4. Optimize
/blog-optimize-images "en/my-topic"
# 5. Validate
/blog-optimize "en/my-topic"
Update Existing Article Images
# 1. Add new images to .backup/
cp ~/new-image.png articles/en/my-topic/images/.backup/
# 2. Reference in article
# 
# 3. Re-optimize (only new images affected)
/blog-optimize-images "en/my-topic"
Storage Considerations
What to Commit to Git
Option 1: Commit Both (recommended for collaboration)
# .gitignore - allow both
# (images/.backup/ and images/*.webp committed)
Option 2: Commit Only Optimized
# .gitignore - exclude backups
articles/**/images/.backup/
Option 3: Commit Only Backups (not recommended)
# .gitignore - exclude optimized
articles/**/images/*.webp
# (requires re-optimization on each machine)
Large Images
For very large originals (>10MB):
- Store backups externally (CDN, cloud storage)
- Document source URL in article frontmatter
- Only commit optimized
.webpfiles
---
title: "My Article"
image_sources:
- original: "https://cdn.example.com/screenshot.png"
optimized: "images/screenshot.webp"
---
Script Cleanup
Optimization scripts are temporary:
# List optimization scripts
ls /tmp/optimize-images-*.sh
# Remove manually if needed
rm /tmp/optimize-images-*.sh
# Or let OS auto-cleanup on reboot
Ready to optimize images? Provide the language/slug path and execute this command.