| name | front-matter-image-converter |
| description | Convert local images referenced in Hugo front matter to modern formats (WebP) and update front matter using ci/convert_page_images.py. |
Front Matter Image Converter
When to use this skill
Use this skill when you need to:
- Ensure images referenced in tool front matter (page bundle resources, hero images, etc.) use modern formats where possible.
- Convert legacy formats (PNG/JPEG/GIF) to WebP and update front matter paths in
index.md.
- Normalize tool icons or other page resources so the site prefers modern image formats.
What this does
The script ci/convert_page_images.py scans index.md front matter, finds local image paths, converts eligible files to .webp, updates the YAML front matter to point at the new files, and deletes the originals after successful conversion.
Supported/behavior notes:
- Converts
.png, .jpg, .jpeg, .gif to .webp.
- Skips
.webp inputs.
- Treats
.svg as non-convertible (left as-is).
.avif is recognized but conversion depends on Pillow build support; if conversion fails, keep the original and report the error.- Only local file paths are processed (no URLs or data URIs).
How to run
Process all tools under content/ (default root):
uv run ci/convert_page_images.py
Process a specific subtree:
uv run ci/convert_page_images.py --root content/tools
Process a single page bundle index:
uv run ci/convert_page_images.py --file content/tools/html/tool-slug/index.md
Adjust WebP quality (1-100, default 80):
uv run ci/convert_page_images.py --quality 85
Post-run checks
- Review
git status to confirm which images were converted and removed.
- Open the updated
index.md front matter and ensure references now point to .webp files.
- Verify any non-convertible images (like
.svg) remain intact.
Troubleshooting
- If a conversion fails for
.avif, leave the original in place and consider keeping it (already modern) or replacing it with WebP manually.
- If front matter YAML fails to parse, fix the YAML and rerun the script.
