Skip to main content
ChapterBind
Troubleshooting

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, inline style="..." 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.png and Chapter 2 uses ch2/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_LINK so 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.