Filename cleaning & the responsive ladder

Filename cleaning

Every output name is derived by:

1. Unicode NFKD normalize, strip combining accents (Ávila → avila).
2. Lowercase.
3. Remove camera/screenshot boilerplate tokens with their trailing number: dsc / dscn / img / imgp / pxl / dji / gopr / photo / image / screenshot / screen shot / capture + digits.
4. Replace every run of non-[a-z0-9] with a single hyphen; collapse repeats; trim ends.
5. Empty result falls back to image.

Examples:

Name collisions are resolved, never silently overwritten

Different sources can reduce to the same stem (DSC_0042.jpg and photo 1.png both → image), and — subtler — a stem ending in a ladder width collides with another image’s variant: hero.jpg emits hero-800.webp, which is also hero-800.jpg’s master. The tool reserves every filename it is about to emit and suffixes the stem (image-2, hero-2) until the whole set is free, so a later image can never destroy an earlier one’s output. Ordering follows the sorted directory listing, so runs are deterministic.

With --name "cosmetic-dentistry-houston" over a folder, the cleaned name is ignored and each file becomes cosmetic-dentistry-houston-1, -2, … (index only added when >1 file). Use --name for SEO; omit it to preserve (cleaned) original names.

The responsive ladder

Default widths: 480, 800, 1200, 1600, 2400. For a source of width W:

• Emit every ladder width < min(W, 2400) as <stem>-<width>.webp.
• Emit min(W, 2400) as the master <stem>.webp (no width suffix) — the primary upload / WP media-library default, and the largest sensible web size (retina-covered; nothing on a page needs more than 2400 for a full-bleed image).
• Never upscale. A 1000px source produces 480, 800, and a 1000px master — no 1200+.

So a 1686px photo → -480, -800, -1200, -1600, and .webp (1686 master). A 1000px graphic → -480, -800, and .webp (1000 master).

Override with --sizes 400,800,1600 (comma list; largest still becomes the un-suffixed master).

Quality

-q/--quality (default 82) is the webp quality for every size. 82 is a strong visual/size balance for photos; drop to ~75 for very large hero images, raise to ~90 for graphics with hard edges/text if artifacts show. Already-small sources aren’t re-encoded upward — if a produced size would exceed the original, you’ll still get webp (usually smaller anyway), but the ladder never invents resolution the source doesn’t have.