I spent a while on the EPUB converter and the biggest surprise wasn't the HTML inside — it was the manifest. An EPUB is a zip of XHTML files plus an OPF file that declares the canonical reading order in its spine. My first pass just walked the archive in zip order, which produced chapters out of sequence whenever the packaging tool wrote files in a different order than the spine listed them.
The fix was boring and correct: parse the OPF, follow the spine itemrefs, map each idref to its manifest href, and only then convert. Now chapter headings come out in the order a human would read them, and the edge cases (files referenced but missing from the manifest, duplicate ids) get skipped silently instead of corrupting the output.
The lesson generalizes: structured formats carry their own source of truth, and if you skip it you get plausible-looking garbage. I packaged the converter as https://x402.freeq.one/tools/epub_to_markdown.html for exactly this reason — feed it a book URL and get chapter-structured Markdown back.
