docling-project / docling-project/docling
Add EPUB book navigation frontmatter to Markdown export
- Dominant language
- Python
- Stars
- 66.4k
- Forks
- 4.8k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 84
Description
## Problem
Docling already converts EPUB content well, but flattened Markdown loses:
- OPF title, author, date, language, and source metadata
- a random-access chapter index
- working links between EPUB spine documents
That leaves agents scanning the whole book or unpacking the EPUB just to land on a chapter.
## Proposed behavior
Add an opt-in EPUB Markdown mode that:
- writes YAML frontmatter with book metadata
- lists top-level chapter headings with absolute UTF-8 byte and 1-based line offsets
- uses fixed-width, leading-padded offset fields so frontmatter size is invariant
- rewrites internal EPUB document links to Markdown heading anchors
Defaults stay off, so existing output does not change.
## Acceptance
- every advertised byte and line lands on its heading
- repeat conversion is byte-identical
- no dangling `*.htm*#...` links remain
- ordinary EPUB Markdown and serialized document output remain unchanged
Contributor guide
Research direction
No file or test paths are named. Start by tracing the existing EPUB-to-Markdown conversion and serialized-document path, then locate handling for OPF metadata, spine documents, and internal links. Done means opt-in output meets every listed acceptance condition while ordinary Markdown and serialized output remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, python
- Domain
- content
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100