PDF Text Extraction#

PDF text extraction in Docling is handled by two backend classes in docling/backend/docling_parse_backend.py: DoclingParseDocumentBackend (serial, default) and ThreadedDoclingParseDocumentBackend. Both delegate all parsing to the C++ docling-parse library, which performs font decoding, character extraction, and layout geometry.

Architecture#

The flow per page:

1. DoclingParseDocumentBackend loads the document into a PdfDocument via DoclingPdfParser 1. The threaded variant uses DoclingThreadedPdfParser and streams PageParseResult objects via iter_pages() 2.
2. On first access, _ensure_parsed() calls dp_doc.get_page() and receives a SegmentedPdfPage containing textline_cells, word_cells, char_cells, and bitmap_resources 3.
3. Coordinate origin flip: docling-parse emits coordinates in bottom-left origin. Every cell list is immediately converted to top-left origin via to_top_left_origin(page_height) 4.
4. get_text_cells() returns textline_cells for the layout pipeline 5; get_text_in_rect() queries cells by bounding-box overlap (≥50% intersection-over-self) for table cell matching 6.

The ContentConfig object controls which cell levels are computed vs. skipped — word/line cells are materialized, raw char cells are computed but not materialized unless keep_chars=True 7. Bitmap rectangles are extracted for OCR region detection; bitmap bytes are never loaded 8.

After layout detection, PageAssembleModel maps clusters to text by consuming textline_cells via sanitize_text().

Backend Options#

PdfBackendOptions is the base config for all docling-parse backends. Key fields:

ThreadedDoclingParseBackendOptions extends the above:

Pass options via PdfFormatOption(backend_options=PdfBackendOptions(...)) to DocumentConverter.

Text Sanitization#

PageAssembleModel.sanitize_text() is applied to every assembled text cluster. Transformations run in order:

1. Dehyphenation — removes end-of-line hyphens when the joined result forms a valid alphanumeric word 9.
2. Typographic character normalization — replaces fraction slash, curly quotes, and bullets with ASCII equivalents 10.
3. Ligature expansion — _LIGATURE_RE matches ligature codepoints (optionally followed by a spurious space before a word character) and replaces them via _LIGATURE_MAP 11:

The ligature map was introduced in PR #3057 and extended for Dutch IJ and U+F0A0 in PR #3254.

Limitation: this normalization only catches ligatures mapped to Unicode codepoints. PDFs that encode ligatures as raw glyph names (e.g., /uniFB01-style references never resolved to Unicode) will not be normalized by this path.

Known Encoding Challenges#

Diacritics / Font Splitting#

Some PDFs render base glyphs and diacritics using different embedded fonts. With enforce_same_font=True (default), docling-parse splits such glyph sequences into separate text cells, producing space-separated fragments (e.g., Zwierząt → Zwierz ą t).

Workaround: set enforce_same_font=False in PdfBackendOptions. This was exposed as a user option in PR #3737 12.

Ligatures#

PDF fonts often encode typographic ligatures as single Unicode codepoints (U+FB00–FB06). Extractors may also insert a spurious space between the ligature glyph and the following characters, breaking words like verification into veri fi cation. The sanitize_text() pipeline handles these cases. See PR #3057 and the open tracking issue 13.

CID-Keyed Fonts / Missing ToUnicode CMap#

CJK PDFs (e.g., Chinese GB/T standards) frequently use CID-keyed fonts with a ToUnicode CMap. When the embedded font subset omits glyph mappings, extraction produces garbled characters (犌犅／犜 instead of correct Chinese text). This is an encoding-level failure, not a rendering failure — force_full_page_ocr cannot recover the correct text because OCR re-reads pixels that look fine visually 14. There is currently no automatic workaround; affected pages require a correctly-encoded source PDF.

GLYPH Artifacts from Type3 / Missing-CMap Fonts#

Before PR #2738, enabling force_full_page_ocr=True replaced textline_cells with OCR output but left word_cells and char_cells intact. Downstream components (especially TableStructureModel) consumed those stale cells, producing GLYPH<c=1,font=/AAAAAH+font000000002ed64673> strings in table content. The fix in BaseOcrModel.post_process_cells() now filters out all non-OCR (from_ocr=False) word and char cells when full-page OCR is active 15, reducing corrupted chunks from 1359 to ~50 in the reported test set.

Key Source Files#

Related issues and PRs:

• PR #3057 — Unicode ligature normalization (U+FB00–FB06)
• PR #3254 — Extended ligature map (Dutch IJ, U+F0A0)
• PR #2738 — Clear word/char cells on force_full_page_ocr
• PR #3737 — enforce_same_font user option
• Issue #3582 — CID-font garbled text with GB/T PDFs
• Issue #3420 — Ligature glyphs generating spaces