To place an image in an EPUB, the manuscript carries notation of this form:
The name you write in the manuscript is not the name the image ends up with inside the EPUB. Not knowing that leads people to open the finished file, fail to find their image, and conclude it was never embedded.
This article covers the notation itself and what happens to the image inside the file. Choosing an image folder and diagnosing images that fail to appear are covered separately.
The notation has three parts
- The image marker — the leading exclamation mark
- The description text — between the square brackets. It is shown when the image cannot be displayed, and read aloud to readers using a screen reader
- The path — between the parentheses, written relative to the folder the manuscript is in
So notation naming an illustration and pointing into an images folder means "embed that file here, described as that text".
The description may be omitted, but should not be. If the image fails to load and nothing appears, a reader has no way of knowing anything was there.
Where hand-writing goes wrong
The notation is short enough to memorise. Two things trip people up.
- Full-width punctuation. Typing the brackets in full-width form produces text, not an image
- The wrong starting point for the path. Writing from the top of the project folder instead of relative to the manuscript
Neither looks wrong when you type it. Nothing surfaces until you preview.
"I inserted it but I can't find it"
The real cost of hand-writing is not the notation. It is not knowing how to confirm the result.
You write the notation, export, unpack the file, and look inside the images folder — where searching for the file name you wrote finds nothing. Inside an EPUB, images are renamed.
I verified this by driving the development build from the command line. With an illustration referenced from the manuscript by its original name, the exported EPUB carried it under a name derived from the body page it belongs to. The original name is not there.
Without knowing that, you conclude the image is missing, doubt the notation, rewrite it, and export again — when it was embedded correctly the whole time.
rune Studio has an insert operation
rune Studio can insert the notation for you: you specify the position, the path, and the description text.
I checked this. Inserting an image at a given line produced correctly formed notation in the manuscript. There is no opportunity to get the punctuation wrong.
Whether it is embedded is answered by inspection
rune Studio can inspect an exported EPUB and report how many images are embedded and whether the body references any image that is not present.
A clean export reported two images — a cover and an illustration — zero missing, verdict valid. No hunting through file names required.
Conversely, moving an image to another folder and exporting flipped the verdict to invalid and named which body file pointed at which missing image.
Scope is manuscript notation
What is treated as this notation is image and link markup inside plain-text manuscript files. It is not every format and every notation.
What to write in the description
The description is not a file label. It is a short statement of what the image conveys to the reader.
For an illustration of a harbour, "plate 1" tells a reader nothing; "ships lined up in the harbour" lets them picture the scene even when the image does not load. The test is simple: does the sentence still work if the image is never seen?
It does not need to be long — one clause is enough. For a purely decorative image, deliberately leaving the description empty is also a defensible choice.
Who this suits, and who is fine without it
It suits people who have just started adding images. It skips the stage of mistyping the notation, and inspection answers the "did it work" question directly.
If you are fluent with the notation and faster by hand, stay with that. It takes seconds once memorised.
Scope note: what was verified is that the notation is inserted and the image is present inside the EPUB. How large it renders in a reading app, and whether its position matches your intent, is outside this.
Summary
- The notation has three parts: marker, description, path — and the description is worth writing
- The name in your manuscript is not the name inside the EPUB
- Not knowing that causes people to "fix" images that were never broken
- rune Studio can insert the notation and can inspect whether images were embedded
For a first step, look at one image reference in your manuscript and check whether the description text is filled in. If it is empty, that is a place where a reader is told nothing.
See the current product scope on the Rune Studio product page.
