OCR / digitization → Digital document (native text layer → Docling)

Docling PDF Parsing Explained: Structure, Traps and Pinning

What it is

A born-digital PDF (exported from Word, LaTeX, a web page, a reporting tool) contains the actual characters with their positions and fonts. No OCR is needed — extraction is exact. What is not free is structure: the PDF format stores glyphs at coordinates, not paragraphs, columns, headings, or tables. A naive extractor (pdftotext) gives you a text soup in drawing order.

Docling (IBM) applies layout analysis and table-structure models on top of the native text layer to reconstruct the document: reading order across columns, heading hierarchy, tables as cells, figures with captions, page and bbox provenance for every element. Output is a DoclingDocument you can export to Markdown/JSON and feed straight into layout-aware chunking (layout / structure-aware).

The same category covers DOCX, PPTX, HTML, XLSX — Docling and similar tools handle them natively, and there the structure is already explicit.

How to implement

  1. Detect the text layer (per-page classification and routing classifier): enough characters, non-garbage. Otherwise route to OCR.
  2. Run Docling with OCR disabled on these pages; enable the layout model and table-structure model (TableFormer). Set do_ocr=False explicitly — Docling will otherwise OCR image regions, which you may or may not want (route figures to the VLM instead, charts, images, diagrams).
  3. Export to a common element schema (layout / structure-aware): iterate doc.iterate_items() for TextItem, SectionHeaderItem, TableItem, PictureItem, with prov giving page and bbox.
  4. Serialize tables as Markdown or HTML; keep the cell grid too (tables).
  5. Strip repeated headers/footers (headers / footers / boilerplate stripping) — Docling labels page headers/footers; drop or demote them.
  6. Validate (production per-page heuristics): min text, no decode garbage, reading-order sanity.
  7. Version the parser (docling@x.y.z, model weights hash) on every element.

Small example

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.base_models import InputFormat
from docling_core.types.doc import SectionHeaderItem, TableItem, TextItem, PictureItem

opts = PdfPipelineOptions(do_ocr=False, do_table_structure=True)
opts.table_structure_options.do_cell_matching = True
conv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

def parse_digital(path: str) -> list[dict]:
    doc = conv.convert(path).document
    elements, heading_stack = [], []
    for item, level in doc.iterate_items():
        prov = item.prov[0] if item.prov else None
        base = {"page": prov.page_no if prov else None,
                "bbox": list(prov.bbox.as_tuple()) if prov else None,
                "parser": "docling@2.x", "breadcrumb": " › ".join(heading_stack)}
        if isinstance(item, SectionHeaderItem):
            heading_stack = heading_stack[: max(item.level - 1, 0)] + [item.text]
            elements.append(base | {"type": "heading", "level": item.level, "text": item.text})
        elif isinstance(item, TableItem):
            elements.append(base | {"type": "table", "text": item.export_to_markdown(doc),
                                    "html": item.export_to_html(doc)})
        elif isinstance(item, PictureItem):
            elements.append(base | {"type": "figure", "text": (item.caption_text(doc) or "")})
        elif isinstance(item, TextItem) and item.label not in ("page_header", "page_footer"):
            elements.append(base | {"type": "paragraph", "text": item.text})
    return elements

Pros

  • Exact characters, no OCR error rate.
  • Fast: seconds per hundred pages on CPU (layout model is the main cost).
  • Structure: headings, tables, reading order, bboxes — everything downstream needs.
  • Offline / self-hosted: no data leaves your environment.
  • Handles DOCX/PPTX/HTML/XLSX with the same output schema.

Cons

  • Layout model still makes mistakes: merged columns, missed headings on unusual templates, table structure errors on borderless tables.
  • Garbage text layers (scanner-embedded OCR, font-encoding quirks, custom glyph maps) look digital but decode wrong. Must detect and re-route.
  • Model dependencies (PyTorch, weights) make the parser heavier to deploy than pdftotext.
  • Throughput per core is bounded by the layout model; big corpora need parallel workers.
  • Tracked-change DOCX, form fields, and annotations need explicit handling.

When to use

  • The default route for every page that passes the text-layer check. In most enterprise corpora that's 70–95% of pages.
  • Office documents of every kind.

When NOT to use

  • Scanned pages (scanned page) — no text layer, or a garbage one.
  • Formula-dense pages where math is the point (formula-heavy page) — Docling's math handling is improving but MinerU/Nougat are better for LaTeX.
  • Pages that are one big figure (charts, images, diagrams).

Production at scale

CPU pool sizing. Digital parsing is CPU-bound (layout + table models in PyTorch). A 4-vCPU worker does roughly 1–3 pages/second with layout+tables on. Run one Docling process per worker with the models loaded once; feed it documents from a queue. Don't spin up a process per document.

GPU optional. Layout/table models run faster on GPU, but at scale the cheaper play is many CPU workers unless you're already paying for GPUs for OCR (then co-locate).

Font-encoding traps. Some PDFs (old LaTeX, certain print drivers, "protected" PDFs) map glyphs to private-use Unicode or ligature codes; text extracts as fi, , or gibberish. Detect via replacement/private-use character ratio and dictionary-word ratio (production per-page heuristics). Re-route those pages to OCR — it's better to read the pixels than trust a broken map.

Reading-order verification. On multi-column pages, Docling's order is usually right; on newsletters and forms it isn't always. Cheap check: sentence continuity across block boundaries (a block ending mid-sentence followed by a block starting mid-sentence = probable order error). Flag for the retry ladder (bounded escalation with visible failure).

Headers/footers. Docling labels them; also run the corpus-frequency approach (headers / footers / boilerplate stripping) because labels miss some. Keep page numbers as metadata, drop them from text.

Version pinning. Docling ships new layout/table weights; output structure changes between versions → different chunks → re-index. Pin the version and the model weights hash; store both on every element. Upgrade via the parsing eval (test-time validation against a golden sample) and a controlled reprocessing wave (change detection).

Timeouts. A pathological 3,000-page digital PDF with thousands of tiny table cells can take an hour. Per-document timeout, per-page timeout, and a "split into parts" path for oversize files.

Determinism. Same input, same version → same output. Verify in CI with a golden-document hash check; this catches accidental nondeterminism (thread-count dependent layout results) that would break chunk-ID stability.

Observability per source. Pages/sec, elements per page by type, table count, heading count, validation failures, re-route rate to OCR. A source whose heading count drops to zero after a deploy is a regression signal.

Prod checklist

  • Text-layer check + garbage-text detection before routing here
  • Docling with do_ocr=False, table structure on; version + weights hash pinned
  • Common element schema with page, bbox, breadcrumb, parser version
  • Header/footer removal (label-based + frequency-based)
  • Reading-order sanity check → retry ladder on failure
  • Persistent worker processes with models preloaded; queue-fed
  • Per-page and per-document timeouts; oversize split path
  • Golden-document determinism test in CI
  • Parsing eval (test-time validation against a golden sample) gate on version upgrades

Metrics to watch

MetricWhy
Pages/sec per workerCapacity
Re-route to OCR rateGarbage text layers
Elements per page by type; heading count per docStructure regression
Table-cell accuracy on golden sampleParser quality
Validation failure rateSilent degradation