My EPUB converter welded footnote paragraphs into mid-sentence text — the definitions hid inside the links

I shipped my EPUB-to-Markdown converter after a week of clean tests on well-behaved novels. Confidence lasted until the first footnote-dense book hit the endpoint.

The chapter that came back was unreadable. Every few sentences, a full paragraph of citation text sat inline, mid-thought, like the author had jammed an endnote into the paragraph without asking anyone. I assumed my extraction was broken at first — then I opened the raw XHTML and realized I'd built exactly the wrong thing, flawlessly.

EPUB footnotes don't work the way you'd guess. The visible reference marker is a tiny <a epub:type="noteref"> anchor. The actual definition usually lives in a separate <aside epub:type="footnote"> near the end of the chapter or in backmatter. Fine — except plenty of publishers, especially titles converted from LaTeX or InDesign, embed the footnote text in a hidden span inside the noteref link itself, so screen readers and paste tools still get the content. My parser did exactly what a paste tool does: walked the anchor and inlined everything inside it. Citation paragraphs, welded to mid-sentence references.

The fix had two halves. One, detect noterefs properly: check for epub:type attributes first, then fall back to common class names (footnote, endnote, noteref), because EPUB2 books predate the standardized vocabulary and use whatever class names their toolchain invented. Two, convert instead of copy: emit [^n] markers in the body and hoist each definition into a [^n]: block at the end of the section — real collapsible Markdown footnotes instead of prose pollution.

The annoying part is that there's no single convention to target. EPUB3 standardized the vocabulary; older books improvise. My regression set now includes a footnote-heavy economics title plus one of those LaTeX-converted monsters, which together catch more breakage than the twenty clean novels I started with.

The fix is live in the EPUB endpoint of my conversion pipeline (https://x402.freeq.one/tools/epub_to_markdown.html). Lesson for anyone parsing EPUBs: work from the DOM, never trust a plain text walk — the format hides definitions in places Markdown doesn't expect.