The reliable way to insert images into EPUB is to treat insertion and packaging as two separate checkpoints. An editor can display a source image while the exported book still points to an old path. The controlled book used here has six chapters, one image role in each chapter, and one cover role. That gives seven routes to follow from source Markdown to the final ZIP.
Name the route before inserting the file
Give each illustration a name that reveals its role, then record the chapter, relative source path, and alt text together. For example, chapter one should refer to its intended file rather than whichever image happens to have the same dimensions. Moving all artwork first and repairing paths later makes it difficult to identify which move broke which chapter. Inserting and reopening one chapter at a time keeps the failure attributable.
The synthetic fixture used six chapter files and a separately registered cover. Each chapter contained one Markdown image reference. The input checklist therefore had six body-image rows and one cover row. Although the test PNGs shared content, their package roles were distinct; the audit counts destinations and references, not artistic variety.
Follow all seven routes inside the exported EPUB
After Rune exported the book, the package was opened as a ZIP. Its spine had ten items, while both navigation documents represented six chapters. XHTML contained seven image references: one in each of p001.xhtml through p006.xhtml, plus one in cover.xhtml. The image manifest contained p001.png through p006.png and cover.png. Seven alt values were recorded, no resource was missing, and local Rune inspection returned valid=true. The EPUB SHA-256 was c826be189be58886a379db2f5cee40e4c499122e2f9a1ee738b701104456dc95.
Matching totals are necessary but insufficient. For every row, resolve the XHTML src to the manifest href, confirm that the ZIP member exists, and compare the alt value with the intended chapter. Two chapters can mistakenly point to the same packaged image while the totals still look plausible. A route-by-route table catches that error because the chapter identity, destination, and description must agree.
Repair the earliest broken link
If only one chapter loses its illustration, return to that chapter’s Markdown. Check filename case, extension, spaces, and the number of parent-directory segments in ../. Do not create a duplicate merely to make the total reach seven; restore the reference to the intended asset. Export under a new name and keep the rejected EPUB so the changed route can be compared.
A missing cover has a different return point. Repair the cover registration without changing accepted body paths. Conversely, when the cover is packaged but a chapter image is absent, leave the cover alone and repair the chapter reference. This prevents a narrow path problem from becoming a new metadata or artwork problem.
Use a seven-row packaging sheet at handoff
The handoff sheet needs chapter name, source path, generated XHTML, XHTML src, manifest href, ZIP presence, and alt text. The seventh row is the cover. Packaging passes when every route resolves and the missing-resource count is zero. Display size and visual quality belong to a reader check, not to this structural result.
This run proves seven packaged roles, seven references, seven alt values, zero missing resources, and local structural validity for the named synthetic fixture. It did not test rendering in third-party readers, retailer ingestion, or image rights. Keeping those limits explicit makes the result useful: a later visual test begins with a package whose internal paths are already known to be complete.
Why this differs from a missing-image warning
A deletion warning tries to prevent a source reference from becoming invalid. This article starts after insertion and asks whether every chosen role reached the package. It therefore does not use the presence of a warning, preview, or successful export message as its acceptance rule. The decisive evidence is the reopened relationship between six chapter references, one cover reference, seven manifest resources, and seven ZIP members.
Test a replacement without changing the whole book
A useful follow-up test replaces only the chapter-four asset. Record the original p004.png digest, place the replacement under a new source name, update only chapter four, and export a new EPUB. The expected difference is confined to the chapter-four route and the generated package member associated with it. If chapter three or the cover changes, the operation was broader than intended and should be rejected.
The same discipline helps when artwork has identical bytes. In this fixture, the synthetic PNG copies share content, but p001.png and p006.png still occupy different package roles. Deduplicating them would change the design being tested. Content identity is therefore recorded separately from route identity. An optimization pass can decide whether sharing one resource is desirable later; the insertion audit should not silently rewrite that decision.
Alt text also needs row-level review. A total of seven alt attributes does not prove that chapter five carries the chapter-five description. Read a representative early chapter, a middle chapter, the final chapter, and the cover. For the remaining rows, confirm that destinations are distinct and nonempty. This balances human review with a complete structural trace without pretending that an automated count evaluates editorial quality.
When another editor receives the EPUB, the useful record is concise: source file and digest, chapter-to-image table, export digest, rejected route if any, repaired route, and unmeasured reader environments. From that record, the editor can decide whether the remaining work is a source-path repair, a package repair, an alt-text edit, or a visual reader test. No one has to infer the state from a screenshot or from a successful export notification.