EPUB
An open e-book standard format that is structured as a ZIP archive containing XHTML content files. Metadata, resource manifests, and reading order are defined by the Open Packaging Format (OPF) specification. EPUB is widely adopted for e-book distribution and reading across devices.
Core Facts
Timeline (last 90 days)
Even if users can import their own EPUB files, details of the reading experience such as layout rendering, fonts, pagination and footnote navigation still require substantial engineering investment.
Amazon Kindle uses the proprietary AZW/KFX format, Kobo uses the Kepub format, and the open-standard EPUB is widely supported.
Alphabetical order, manifest order, or ID naming does not guarantee alignment with the actual human reading order.
The file list is not the reading order, and the table of contents is not the structure either; one should find the manifest that expresses the intent and follow it.
Linear text extraction breaks non-linear books: footnotes, sidebars, and quotation boxes are separate XHTML files referenced inline in the body text, and simply extracting text in spine order would omit them or insert them in the wrong place.
Parsing the spine is the correct way to determine EPUB reading order: for each itemref, resolve its ID to the manifest entry and then read the corresponding file; if a spine entry points to a non-XHTML resource, it should be skipped gracefully.
In EPUB spine entries, the linear="no" attribute indicates that the document is auxiliary content that can be skipped during linear reading.
EPUB's table of contents file (NCX or nav.xhtml) only describes the navigation structure and may be inconsistent with the spine order, so it cannot serve as the source of truth for reading order.
Fixed-layout EPUBs (fixed-layout books where each page is an image) cannot be handled with a text approach and require detection and fallback to OCR or a PDF-like pipeline, which remains an open problem.
lxml may turn <p></p> into <p/>, which causes errors in some readers, so the team ultimately switched to a more tolerant HTML parser to handle the many EPUBs that are not strictly valid XML.
14 more timeline events
All Facts (20)
An EPUB is essentially a ZIP archive filled with XHTML files
65%UnverifiedEven if users can import their own EPUB files, details of the reading experience such as layout rendering, fonts, pagination and footnote navigation still require substantial engineering investment.
50%UnverifiedAmazon Kindle uses the proprietary AZW/KFX format, Kobo uses the Kepub format, and the open-standard EPUB is widely supported.
50%UnverifiedAlphabetical order, manifest order, or ID naming does not guarantee alignment with the actual human reading order.
50%UnverifiedThe file list is not the reading order, and the table of contents is not the structure either; one should find the manifest that expresses the intent and follow it.
50%UnverifiedLinear text extraction breaks non-linear books: footnotes, sidebars, and quotation boxes are separate XHTML files referenced inline in the body text, and simply extracting text in spine order would omit them or insert them in the wrong place.
50%UnverifiedParsing the spine is the correct way to determine EPUB reading order: for each itemref, resolve its ID to the manifest entry and then read the corresponding file; if a spine entry points to a non-XHTML resource, it should be skipped gracefully.
50%UnverifiedIn EPUB spine entries, the linear="no" attribute indicates that the document is auxiliary content that can be skipped during linear reading.
50%UnverifiedEPUB's table of contents file (NCX or nav.xhtml) only describes the navigation structure and may be inconsistent with the spine order, so it cannot serve as the source of truth for reading order.
50%UnverifiedFixed-layout EPUBs (fixed-layout books where each page is an image) cannot be handled with a text approach and require detection and fallback to OCR or a PDF-like pipeline, which remains an open problem.
50%Unverifiedlxml may turn <p></p> into <p/>, which causes errors in some readers, so the team ultimately switched to a more tolerant HTML parser to handle the many EPUBs that are not strictly valid XML.
50%UnverifiedA large number of EPUBs in the wild are not valid, so the team implemented a fallback strategy: first attempt strict XML parsing, and on failure use the lxml.html parser.
50%UnverifiedThe team used more than 50 books from different sources for regression testing.
50%UnverifiedPreserve the original DOM as much as possible—even deleting an empty span may break the layout; plan the handling of inline tags early, and stripping tags is only a temporary solution.
50%UnverifiedWhen processing Markdown or EPUB-format e-books, it is necessary to first perform structured parsing and remove non-readable content such as Markdown heading symbols, footnote markers, and image links, otherwise problems such as reading heading symbols aloud and footnotes being mixed into the body text will occur.
50%UnverifiedThe pragmatic approach for handling corrupted chapters is to skip them and continue rather than letting the entire book conversion fail, in order to be more robust against real-world data
50%UnverifiedEPUB content files are strict XML rather than lenient HTML; a stray entity or unclosed tag can crash a strict XML parser
50%UnverifiedThe correct parsing process is: read container.xml to locate the OPF, parse the manifest to build an id-to-href mapping, then traverse and convert in the itemref declaration order of the spine
50%UnverifiedOPF (Open Packaging Format) is a core component of the EPUB specification; it is essentially an XML file, typically named content.opf but not required to be
50%UnverifiedThe alphabetical order of EPUB filenames has no relationship to the reading order of the book
50%