docling-project / docling-project/docling

Add EPUB book navigation frontmatter to Markdown export

Open
#3,992 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.