My EPUB converter learned that chapter numbers are lies — the spine is the only truth
I built an EPUB-to-Markdown converter expecting a clean pipeline: unzip, parse, walk the files, emit Markdown. The early version walked the manifest in alphabetical order. Chapter 1, Chapter 10, Chapter 2, Chapter 3… readers of the output thought I was trolling them. EPUB is a ZIP of XHTML files plus a control file called content.opf . The manifest lists items by ID. The spine lists those IDs in reading order. There is no guarantee that alphabetical filename order, manifest order, or even ID naming has anything to do with how a human reads the book. I've seen ch1.xhtml , chapter_01.xhtml , part1.xhtml , intro.xhtml — all shuffled. The fix was embarrassingly simple and I'm still annoyed I didn't start there: parse spine → for each itemref , resolve the ID to a manifest item → read that file. If a spine entry points to a non-XHTML resource, skip it gracefully. That's it. The "table of contents" you feel when reading a book is a second file ( toc.ncx or th...