Version Blog Images Alongside the Copy They Explain
Version blog images with their related copy so diagrams, screenshots, captions and descriptions remain consistent through revisions.
TL;DR
- Treat images as part of the article revision: assign each asset a stable identity and revision so visuals remain aligned with the accompanying caption and prose during updates.
- Use paired sources and outputs plus coordinated review: keep editable source files with the rendered asset, record them in a manifest, and inspect image and copy together as a release package.
- Require an explicit verification and rollback plan: retain previous approved assets, confirm the delivered page and mobile presentation, and record the accepted article revision in the manifest.
An image belongs to an article revision
Blog image versioning should keep the visual explanation aligned with the words around it. Replacing a diagram without updating the caption can leave the article internally inconsistent even when both files look polished.
Give each asset a stable identity and a revision. Record which article revision uses it, why it changed and whether the associated description needs review.
A conceptual diagram and a product screenshot need different checks. A diagram should accurately explain the intended model. A screenshot should represent the relevant product state and must not imply a feature exists merely because an illustration looks like an interface.
Keep the editable source and released output
Store the source used to create the image alongside the rendered asset or an unambiguous reference to it. For a diagram, that might be an SVG and its PNG output. For a screenshot, retain enough capture context to reproduce it appropriately.
Do not rely on a filename such as final-final-new.png. Use a stable asset ID, revision number and manifest entry.
| Asset record | What it should explain |
|---|---|
| Identity | Which visual this is across revisions |
| Source | Where an editor can make a legitimate update |
| Output | The exact file used in the article |
| Context | Diagram purpose or screenshot conditions |
| Related text | Caption, description and article section |
A content hash can help verify that the intended file was uploaded, but it does not replace a meaningful description of the asset's purpose.
Review the image and copy together
Open the rendered article after an asset change. Check labels against the surrounding explanation, inspect the caption and confirm that any numbered steps still correspond.
For an illustrative example, suppose a workflow diagram changes from three review stages to four. The article may still say “the three stages below,” and the caption may name a stage that no longer exists. A file-only review would miss both issues.
Our content approval workflow can treat the image and copy as one release package. Acceptance should identify the actual version inspected.
Make replacement behavior explicit
Understand whether replacing a file changes every page that uses its URL or only the current article. A shared asset can be convenient, but a global replacement may alter older pages unexpectedly.
For a substantial change, a new versioned URL can make the relationship clearer. Record which pages should adopt it and which should retain their earlier visual for historical context.
Do not assume a successful upload means the public page displays the new file. Inspect the delivered page and confirm the expected image, especially when an existing URL was reused.
Retain an intentional rollback path
Keep the previous approved asset until the new article revision is verified. If the replacement contains an error, the team should be able to restore a consistent copy-and-image pair.
A rollback should not restore only the old image while leaving new labels in the prose. Record the compatible article revision or update both components together.
The guide to updating old posts provides the wider maintenance process. Asset versioning supplies the evidence needed to know what changed visually.
Close the revision with a public check
Confirm that the image loads, remains readable at the article's displayed size and matches its description. Check mobile presentation as well as the full-size source.
Record the uploaded file and the accepted article revision in the manifest. If an obsolete asset is no longer used, remove it only according to the team's retention process and after checking its references.
The result should be a traceable visual history, not a folder full of almost-identical files. Another editor should be able to identify the current image, explain its purpose and update it without breaking the article's meaning.