Batch Image Conversion, Naming and Folder Conventions

A batch conversion without a filename rule produces files nobody can match to the CMS. Keep the masters untouched, write every export with the same pattern, and log the run. The WebP Converter handles one image at a time in the browser. It does not rename a folder on disk. For hundreds of files, pair the naming rule with a local script and a CSV manifest.

A deploy broke hero images because one folder held banner.webp, banner (1).webp, banner-final.webp, and banner_final_v2.webp. The CMS expected homepage-hero-1200w.webp. Nobody could say which script had written which file.

Principles

1. Masters stay immutable. Do not overwrite originals.
2. The pattern should sort for a person and for a script.
3. The extension should match the actual file.
4. The variant should be explicit: width, purpose, or density in the name.
5. One project gets one convention, written down in a README.

See batch renaming before upload.

Filename pattern

{project}_{asset}_{variant}_{width}w.{ext}

Examples:

• adsense_hero_desktop_1200w.webp
• adsense_icon_search_32w.png
• blog_phishing-diagram_featured_1600w.jpg

Use lowercase. Prefer hyphens when the files will be imported to a static host as URLs.

A consistent pattern looks like project_asset_variant_size.format, for example homepage_hero_desktop_1200w.webp.

Folder structure

assets/
  originals/
    hero.psd
    hero-master.png
  export/
    webp/
    jpeg/
    png/
  archive/
    2026-10-batch/

Or by route:

public/images/blog/phishing-pdf-attachments/
  featured-1200w.webp
  diagram-metadata-800w.webp

Other layouts that work: project/originals/, project/export/webp/, project/export/jpeg/, or /blog/post-slug/images/ when you want the folder to mirror the CMS import path.

Tools

Browser tools convert small sets one file at a time: WebP Converter, PNG to JPG, JPG to PNG, and Resize Image.

Use the command line for volume:

# illustrative — adjust tools to your stack
for f in originals/*.png; do
  cwebp -q 85 "$f" -o "export/webp/$(basename "${f%.png}").webp"
done

Log each conversion in manifest.csv: source, output, date, and quality.

Responsive sets

Retina images at 2x means exporting 1x and 2x with the width in the filename.

If a CDN builds the variants, local names can be simpler. See image CDN vs browser resize.

SVG to raster

When you need a raster from SVG, make the size explicit: logo.svg becomes logo-512w.png. See SVG to PNG when needed.

Compression after the name is final

Compress with Compress Image after the final name exists. Compressing before that breaks the trail from source to output. See how image compression affects quality.

CMS and import problems

• Spaces become %20 in URLs.
• Uppercase extensions break deploys on Linux.
• Reusing the same name fights the CDN cache. Use a version suffix such as hero-v3.webp, or a content hash.

Dark mode pairs

For dark mode screenshots, suffix _dark or _light, as in docs-editor_dark_1200w.png.

Git LFS and committed binaries

A repository past 500 MB of images is a candidate for Git LFS, with pointer files and a CI step that pulls LFS at build time. The filename convention matters more when the bytes are spread across LFS.

A checksum in the manifest

Add a SHA-256 column so a bad copy is detectable. On Linux, sha256sum. On Windows, CertUtil -hashfile.

Retiring an old export

Keep hero-v2.webp as the live file and move hero-v1.webp to archive/. If you will not need a rollback, put a reminder on the calendar to delete v1 from the CDN after 90 days.

Worked example: a blog batch

Imagine a post with eight screenshots. Without a convention you get image1.png through image8.png. Six months later, nobody can say which file shows the merge dialog.

A clearer pipeline:

1. Save masters to originals/blog-merge-guide/.
2. Crop each image in Crop Image.
3. Export merge-guide_step-01_upload_800w.webp through step-08_download.
4. Log the batch in manifest.csv with the source hash and the quality setting.
5. Reference the file in MDX: ![Upload step](/images/blog/merge-guide/merge-guide_step-01_upload_800w.webp)

When Search Console still shows an old image URL, you know which file to replace. You do not have to guess at a rename.

Agency handoff

An agency delivering assets should document the names in the handoff, as a one-page NAMING-CONVENTION.md in the deliverables folder. The client development team inherits the structure, and arguments drop 90%. Include examples of wrong names, marked with a red X. Humor helps compliance.

Automation failures

A watch-folder script can fire twice and write both file.webp and file-1.webp. Debounce the script, or move the source to processed/ after a successful conversion. A failed conversion should log an error. A silent skip produces a missing image in the production build, and CI will not catch it if the MDX points at the wrong path.

Limitations

A browser converter processes one file at a time and does not rename folders on disk. For hundreds of assets, pair the naming convention with a local script (cwebp, ImageMagick, or sharp) and a CSV manifest.

When production breaks

originals/, one pattern, and a manifest should exist before you convert fifty PNGs to WebP. homepage-hero-1200w.webp is findable at 11 PM. banner (1).webp is not. Name the file as if someone else will deploy it without asking you.