Skip to content

Conversation

@bigbag
Copy link

@bigbag bigbag commented Dec 31, 2025

Summary

  • What is the goal of this PR? Add EPUB 3 support by implementing native navigation document (nav.xhtml) parsing with NCX fallback, addressing issue #143.

  • What changes are included?

    • New TocNavParser for parsing EPUB 3 HTML5 navigation documents (<nav epub:type="toc">)
    • Detection of nav documents via properties="nav" attribute in OPF manifest
    • Fallback logic: try EPUB 3 nav first, fall back to NCX (EPUB 2) if unavailable
    • Graceful degradation: books without any TOC now load with a warning instead of failing

Additional Context

  • The implementation follows the existing streaming XML parser pattern using Expat to minimize RAM usage on the ESP32-C3
  • EPUB 3 books that include both nav.xhtml and toc.ncx will prefer the nav document (per EPUB 3 spec recommendation)
  • No breaking changes - existing EPUB 2 books continue to work as before
  • Tested on examples from https://idpf.github.io/epub3-samples/30/samples.html

  - Add TocNavParser for HTML5 navigation documents
  - Detect nav document via properties=nav in OPF manifest
  - Try nav.xhtml first, fall back to NCX for compatibility
  - Books without TOC now load with warning instead of failing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant