HTML to EPUB Troubleshooting: Missing Images, TOC & Reflow Fixes
Most conversion surprises come from relative file paths, remote image restrictions, or web-specific CSS that does not belong inside a reflowable ebook.
1. Missing Local Image Warnings (MISSING_IMAGE)
If you upload only an .html file without its companion image folder, ChapterBind reports each unresolved <img src="..."> path as a warning instead of failing silently.
- Quick inline fix: Open the Diagnostics & Issues panel and click Attach file beside any missing image path to map the image directly.
- Re-import with folder: Click Select Folder and choose the parent directory containing both your HTML file and its
images/or_files/subfolder. - Remote
https://image URLs: ChapterBind never fetches external URLs during conversion. Save those images locally and update the relative path if you need them offline.
2. Why Webpage Layout Changes in Reflowable EPUBs
E-readers intentionally override webpage navigation bars, multi-column sidebars, and fixed pixel widths so text can wrap at any zoom level.
- ChapterBind strips raw
<style>blocks, inlinestyle="..."attributes, forms, iframes, and scripts, replacing them with a lightweight reflowable stylesheet (EPUB/styles/ebook.css). - Images use
max-width: 100%; height: auto;so wide diagrams shrink proportionally to fit narrow e-ink screens without clipping. - If your HTML relies on interactive charts or JavaScript-rendered content, export static text and raster PNG/JPEG figures before converting.
3. Missing or Out-of-Order Table of Contents Entries
The EPUB 3 Table of Contents (EPUB/nav.xhtml) mirrors the chapter order in your workspace plus nested h1–h3 headings inside each chapter.
- If a chapter lacks semantic heading tags (for instance, bold
<p><strong>Title</strong></p>instead of<h2>), only the top-level chapter title appears in the TOC. - Rename chapters inline on the left panel before clicking Convert to EPUB to customize the TOC labels without editing your source HTML.
4. Duplicate Image Filenames & Broken Internal Links
- Duplicate image basenames across folders: If Chapter 1 uses
ch1/fig.pngand Chapter 2 usesch2/fig.png, ChapterBind assigns distinct manifest names (img-01-fig.png,img-02-fig.png) so neither overwrites the other. - Unmatched local HTML links: Links pointing to HTML pages you did not import into the current book are converted to plain text and flagged under
BROKEN_INTERNAL_LINKso EPUBCheck reports zero dead link errors.
5. Reader Compatibility Notes
Generated books conform to EPUB 3.0 / 3.3 and are verified with W3C EPUBCheck 5.1.0. Note that some older hardware e-readers with legacy EPUB 2 firmware may ignore advanced HTML5 landmarks while still displaying chapters, images, and the primary Table of Contents; testing a sample chapter on your target device is always recommended.