pro-ledin-docling-ebook

Open Docling backend extension for structured ebook conversion.

It converts EPUB, FB2, compressed FB2, and DRM-free MOBI-family books into a native DoclingDocument, then exports through Docling to Markdown, JSON, or HTML.

• Inputs: .epub, .fb2, .fb2.zip, .fbz, .mobi, .azw, .azw3
• Python package: pro.ledin.docling_ebook
• CLI: docling-ebook
• License: MIT
• Proprietary dependencies: none

Install

pip install pro-ledin-docling-ebook

The package uses the official docling-slim distribution because ebook conversion needs the Docling document model and backend contracts, not PDF layout, OCR, or VLM models.

EPUB and FB2 work immediately. DRM-free MOBI/AZW/AZW3 require one external converter. mobitool is preferred; Calibre is the fallback:

brew install libmobi
sudo apt install libmobi-tools

Calibre downloads: https://calibre-ebook.com/download

docling-ebook doctor --json

CLI

docling-ebook book.fb2 --to md --output-dir ./out
docling-ebook book.mobi --to json --output-dir ./out
docling-ebook one.epub two.azw3 --to html --output-dir ./out

Preview parsing without writing outputs:

docling-ebook book.fb2 --dry-run

Source image policy:

docling-ebook book.fb2 --images import
docling-ebook book.fb2 --images skip

Docling export image mode:

docling-ebook book.fb2 --to md --image-mode placeholder
docling-ebook book.fb2 --to md --image-mode embedded
docling-ebook book.fb2 --to md --image-mode referenced

MOBI backend selection:

docling-ebook book.azw3 --mobi-backend auto
docling-ebook book.azw3 --mobi-backend mobitool
docling-ebook book.azw3 --mobi-backend calibre

Footnotes default to Markdown-compatible native markers. Use an inline fallback when a downstream Docling consumer does not preserve footnote references:

docling-ebook book.fb2 --footnote-mode inline --to md

Python API

from pro.ledin.docling_ebook import EbookConverter

result = EbookConverter(
    image_mode="import",
    mobi_backend="auto",
).convert("book.fb2")

document = result.document
result.save_as_markdown("book.md", image_mode="embedded")
document.save_as_json("book.json")

Streams require a filename so the ebook format can be detected:

from io import BytesIO
from pro.ledin.docling_ebook import convert_ebook

result = convert_ebook(BytesIO(payload), filename="book.fb2")

Native document mapping

The backend maps the typed pro-ledin-ebook-import model directly into DoclingDocument:

• book title and metadata
• chapter and nested-section groups
• headings and paragraphs
• mixed emphasis, bold, strike, links, code, subscript, and superscript
• epigraphs, citations, poems, stanzas, and verse lines
• tables with row/column spans
• content and cover pictures
• footnote references and definitions
• ordered and unordered lists

Warnings and MOBI converter provenance remain available on EbookConversionResult instead of being inserted into book text.

Docling extension boundary

Docling's third-party plugin entry point currently registers OCR, layout, table-structure, and picture-description models. It does not register new input formats or document backends. This package therefore provides the public EbookDocumentBackend, EbookConverter, and docling-ebook CLI rather than an irrelevant model-plugin entry point.

The stock command below is not provided by an external backend package:

docling --from fb2 book.fb2

Native support for that syntax requires new InputFormat and CLI mappings in Docling upstream. This extension uses only public InputDocument and DeclarativeDocumentBackend APIs and does not call private Docling methods or model pipelines. The converter invokes the public DeclarativeDocumentBackend.convert() contract directly, so docling-slim does not pull PDF/OCR/VLM dependencies.

An alternative commercial project, aspose-words-docling, supports some ebook formats through Aspose.Words. This package instead uses the open pro-ledin-ebook-import parser and libmobi/Calibre subprocess boundary.

Safety

• FB2 XML rejects DTD and entity expansion.
• FB2.ZIP/FBZ archives enforce path, size, member-count, and compression limits.
• External converters run without a shell in temporary directories.
• Remote Docling services and external model plugins remain disabled.
• The package never removes DRM and rejects encrypted books.
• KFX, AZW4 Print Replica, and PRC are unsupported.

Development

uv sync --extra dev
uv run --extra dev pytest -q -m "not external"
uv run --extra dev pytest \
  --cov=pro.ledin.docling_ebook --cov-branch --cov-report=json
uv run python scripts/check_coverage.py coverage.json
uv build

Run real MOBI converter integration when both tools are installed:

DOCLING_EBOOK_EXTERNAL_TESTS=1 \
  uv run --extra dev pytest tests/test_real_mobi_tools.py

License

MIT