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 anchor. The actual definition usually lives in a separate 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. Top comments (0)