Edit EPUB Sources Without Garbled Text or Broken Images

After editing an existing EPUB source set, do not restart a generic inspection from zero. Freeze the pre-edit baseline, record the exact text and image deltas, and define a separate rollback point for each kind of change. If the edited output fails, restore only the affected side instead of disturbing chapters and assets that were not part of the edit.

This article starts with an established three-chapter source containing three inline images. Its role is post-edit control: what was true before the edit, what was intentionally changed, what had to remain unchanged, and where to roll back. It is not an intake checklist for a newly received manuscript.

Freeze a pre-edit baseline

Before changing the source, record a compact baseline.

The baseline is not a complete defect inventory. It separates what this edit may change from what must not change. Keep a duplicate under a distinct name rather than overwriting it with the edited source.

Split the change ticket into text and image deltas

A combined change note gives no clear rollback point. Use one record for text and another for images.

Record location and approval for each text delta

For a text change, record chapter ID, line, old value, new value, and the reason for accepting it. If a private-use character appears in a name, do not choose a visually similar substitute by guesswork; preserve the author or editor’s approval.

Rune Studio’s published documentation describes detection of major Japanese encodings, display of unconvertible characters, and suspended autosave while such problems remain. The article-specific run did not exercise the complete interaction from two candidates to a zero-candidate result. Treat that behavior as published feature information and test it on a duplicate of the current source rather than presenting it as an observed result here.

Keep old and new image references together

For an image edit, record chapter ID, old reference, new reference, real file, and rollback location. If C01.md changes from ../old/map.png to ../images/map.png, verify both that the stale reference is gone and that the new reference resolves to the intended file.

Do not relocate chart.png or note.png if they are outside this change. A fixed unchanged scope lets a later missing image be classified as part of the current delta or as a pre-existing condition.

Reinspect the delta after editing

Compare the edited copy with the baseline and the two change records.

1. Confirm that only the two recorded text locations changed to the approved values.
2. Reopen C02.md and reconcile its surrounding text and explained character-count change.
3. Search for the old image reference and confirm that its one targeted use is gone.
4. Confirm that the new reference occurs once and resolves to the intended file.
5. Compare the two unchanged image references, chapter order, and navigation labels with the baseline.

The acceptance condition is not merely “zero character candidates” plus “zero missing images.” The planned delta must be present, and the unchanged scope must still match the pre-edit baseline.

Define rollback points before export

If a replacement character is wrong, leave the images alone and restore the pre-edit copy of C02.md. If an image is missing, preserve the approved text delta and restore only the reference-and-file pair for C01.md. If chapter order or navigation labels changed, return to the baseline for output selection rather than either delta record.

After a rollback, repeat the check for the restored side. A previously accepted record for the other side does not need to be discarded unless both changes share the same file; in that case, reopen the file and reconcile it with both records.

This prevents a missing image from triggering an encoding change, or a text defect from triggering an asset relocation.

Read the output against the baseline

The article-specific horizontal EPUB used three source chapters, three inline images, and one cover. Its spine contained cover, title, navigation, three content documents, and colophon. Inspection found four packaged images—the expected cover plus three figures—and no missing images. Navigation and NCX were present, and the local structural result was valid=true.

That result supports the image-side package outcome. It does not establish that two character candidates were repaired to zero. valid=true also does not prove retailer acceptance or identical rendering in every reader.

Do not accept the output result in isolation. Compare it with the pre-edit baseline: three chapters remain three, the three inline images and cover are packaged, and navigation is present. Any difference outside the planned delta keeps the edited output on hold.

The W3C EPUB 3.3 specification is the general reference for the distinct roles of the manifest, spine, and navigation document.

Where delta control applies

This method fits a limited text correction or image-reference change in a source set that already has a known state. It does not cover initial intake inspection, recovery of an already damaged EPUB, image rights or visual quality, or retailer-side recompression.

If no pre-edit baseline exists, freeze the current duplicate as a provisional baseline. Do not invent an earlier state from memory; record deltas from that point forward.

Conclusion

To prevent garbled text and broken images after an EPUB edit, fix five things before changing the source: the pre-edit baseline, text delta, image delta, unchanged scope, and rollback point. Passing means that the intended delta is present and everything outside it still matches the baseline, not merely that two issue counters show zero.

Start by duplicating the existing source and writing the planned text and image-reference changes on separate lines. Current Mac features and download options are available on the Rune Studio website.