Build from three records before export
The central task in building an EPUB file with images is to define the source of truth before producing an artifact. Create a source-reference record, a packaged-resource record, and a reading-order record. Give every row a comparison key and a return point for mismatches. In the controlled two-chapter sample, this design led to three packaged images, zero missing resources, and two chapter links.
This article is about constructing those records and connecting their rows. It is not another plan-export-inspect completion rule, and it does not decide KDP acceptance or visual rendering on every device.
Put source, relative path, and role in the reference record
The inputs were chapter01.md and chapter02.md. Each chapter referenced one inline image, and a separate image was assigned as the cover. The source-reference record needs at least the source, the path or setting, and the asset role.
| Source | Recorded item | Role |
|---|---|---|
| chapter01.md | First relative image reference | Inline image |
| chapter02.md | Second relative image reference | Inline image |
| EPUB settings | Selected cover asset | Cover |
Combining these as “three images” would hide the correct repair location. An inline-image mismatch returns to a chapter source; a cover mismatch returns to the cover assignment. Store that distinction in the record rather than reconstructing it after export.
Connect source roles to package counts in the resource record
The packaged-resource record contains the image resources and their manifest registration. The article-specific result reported image_count=3 and missing_images=0. The expected package count comes from two inline-image rows plus one cover row in the source record.
The comparison key is not only a filename. Use the role—inline image or cover—together with the expected count. If the package contains only two images, return to the source record to determine whether a chapter reference or the cover assignment is missing. Do not add an asset directly to the generated EPUB, because that would disconnect the artifact from its source record.
Map each manuscript chapter to generated order
The reading-order record connects source order with generated chapter links. In this run, both nav.xhtml and NCX were present, each with two items. The nav targets were p001.xhtml and p002.xhtml; the NCX targets were Text/p001.xhtml and Text/p002.xhtml.
| Source order | nav | NCX | Return point |
|---|---|---|---|
| chapter01.md | p001.xhtml | Text/p001.xhtml | First chapter selection and order |
| chapter02.md | p002.xhtml | Text/p002.xhtml | Second chapter selection and order |
The reported spine_count=6 also includes cover, title, navigation, and colophon documents. It does not need to equal the two source chapters. The useful key is the one-to-one order from the two manuscripts to p001 and p002 in both navigation representations.
Send each mismatch back to its row
The three-record method gives each difference a bounded repair:
- A source-reference row exists but the package count is low: return to that chapter’s relative path and source asset.
- The cover row exists but the cover resource is absent: return to the cover assignment.
- Three image resources are present but the chapter-link count is not two: return to manuscript selection and order.
- nav and NCX disagree on their targets: return to table-of-contents inclusion and package generation.
The goal is not to rebuild everything whenever an image is missing. Use the comparison key to select one row, preserve the records as the source of truth, and rebuild from corrected input.
The controlled sample connected all three records
The article-specific Stage 4 run created two chapters, two inline images, and one cover, then generated the EPUB after setting series, volume, cover, and manuscript inputs. The result was image_count=3, missing_images=0, spine_count=6, nav_item_count=2, ncx_item_count=2, and valid=true.
Those observations connect three source rows, three packaged image resources, and two reading-order rows in this local artifact. A separate common Stage 4 sample used four chapters, one image, and eight spine items. Its values belong to a different sample and are not used to fill this article’s records.
Keep valid true inside the local package boundary
The article-specific status is passed, but only for the locally inspected EPUB package. The run did not verify image appearance, resolution, alt-text quality, every reader, or KDP acceptance. valid=true means the recorded inspection reported no missing required item; it is not a retail or universal-rendering guarantee.
The EPUB 3.3 specification gives the package manifest, spine, and navigation document different roles. Those general roles support separate records, but the record design is an editorial workflow, not an EPUB requirement or a Rune-specific invention.
Use Rune Studio as the local construction tool
Rune Studio’s documented Mac workflow can select workspace manuscripts, collect metadata and cover settings, and generate an EPUB 3 package containing content.opf, nav.xhtml, NCX, content documents, and images. This does not imply unconditional support for every Markdown construct.
The values in this article are separate Stage 4 observations from a dedicated CLI sample. Rune Studio is the construction tool, the three records are the source of truth for this method, and Stage 4 is the measured result. Keeping those roles separate prevents documented capability from being mistaken for a completed row.
Conclusion: create the rows before generating the EPUB
For this sample, the source-reference record held two inline-image rows and one cover row, the packaged-resource record held three images and zero missing resources, and the reading-order record mapped the two manuscripts to p001 and p002. A mismatch returns to the specific source, cover, or order row.
That is the distinctive method for building an EPUB file with images: define the records and comparison keys before export so that every repair and rebuild starts from the same source of truth. This sample connected the records through the local package result; retailer and device checks remain separate.
