WordPress can generate multiple sizes when an image is uploaded, and themes or plugins can add more. A reliable workflow begins before the Media Library: preserve an archival master, create a publication derivative, use a descriptive filename, and verify the responsive markup on the live page.
Publish an accessible, maintainable image without losing the source or creating unexplained derivatives.
Repeatable method
1. Separate master and web derivative
Keep the original in controlled storage. Export a web-ready derivative at a justified maximum width and format; do not use WordPress as the only archive.
2. Name and describe in context
Use a short descriptive filename. Write alt text for the image’s purpose on this page, not a keyword list or a copy of the filename.
3. Inspect generated sizes
Review Settings > Media and theme registrations. Upload one test file and list the generated derivatives before bulk publishing.
4. Verify the rendered HTML
On the published page, inspect src, srcset, sizes, width, height, loading, and currentSrc. Confirm the browser did not receive the full master for a small slot.
Use a reversible upload fixture
Before changing a live media workflow, prepare one non-sensitive source image and a named test page. The purpose is to document what WordPress creates and serves, not to claim that one format or setting is universally best. Keep the original outside the Media Library until you decide what must be retained.
| Checkpoint | Field to register |
|---|---|
| Source | Filename, dimensions, format, bytes, license, and alt-text context |
| Upload | WordPress version, active theme, and registered image sizes |
| Generated files | Filename list and dimensions observed after upload |
| Placement | Test-page URL, block/template, and CSS slot width |
| Delivery | Actual currentSrc, transferred bytes, and viewport/DPR |
| Rollback | How the test media and page can be removed or restored |
Use fictional or licensed material only. If the served candidate differs from the intended one, preserve that observation and investigate the markup before changing optimization settings.
What to record
Record master location, derivative filename, export settings, upload date, attachment ID, generated sizes, page URL, rendered slot width, selected currentSrc, and who reviewed alt text.
A result belongs to the source file, encoder, settings, browser, viewport, cache state, and date that produced it. Repeat the test on representative files before changing a production workflow.
Common mistakes
- Uploading the only copy of the original
- Using generic filenames such as IMG_0042
- Writing alt text for search engines instead of people
- Assuming the selected editor size equals the network response
Verification checklist
Open the page logged out, test mobile and desktop viewports, inspect the selected candidate, confirm dimensions reserve space, search the media filename for duplicates, and verify the master is backed up elsewhere.
Primary references
Related lab notes
About this guide
We distinguish documented platform behavior from our workflow recommendations. See the testing methodology, editorial policy, and corrections log.