pdf-to-html-docling

v1.0.152

Published

7 hours ago

0High
0Medium
0Low

vtempest

PDF To HTML with Docling OCR Model

Convert PDF documents to HTML using the ibm-granite/granite-docling-258M AI model from Hugging Face.

This system processes documents by extracting text with OCR while preserving layout, structure, and bounding boxes. It supports recognition of code, formulas, tables, lists, charts, and figures, ensuring accurate formatting and correspondence of captions. Full-page conversion integrates all elements—text, equations, tables, and graphics—into a cohesive output. It is designed for both scientific and non-scientific documents, offering comprehensive document processing capabilities.

Features

📄 Convert complex PDF files to structured HTML
🤖 Uses advanced Granite Docling AI model for accurate text extraction
📐 Layout and Localization – Preserves document structure and document element bounding boxes.
💻 Code Recognition – Detects and formats code blocks including identation.
🔢 Formula Recognition – Identifies and processes mathematical expressions.
📊 Chart Recognition – Extracts and interprets chart data.
📑 Table Recognition – Supports column and row headers for structured table extraction.
🖼️ Figure Classification – Differentiates figures and graphical elements.
📝 Caption Correspondence – Links captions to relevant images and figures.
📜 List Grouping – Organizes and structures list elements correctly.
📄 Full-Page Conversion – Processes entire pages for comprehensive document conversion including all page elements (code, equations, tables, charts etc.)
🔲 OCR with Bounding Boxes – OCR regions using a bounding box.

Installation

This package lives inside the qwksearch-research-agent monorepo at packages/extract-pdf-docling. There are two implementations included: a Node.js/Hono HTTP API (default, runs the ONNX model via Transformers.js — no GPU or Python required) and a Python/FastAPI service (uses PyTorch + the full docling-core pipeline).

Prerequisites

Bun >=1.3 (the monorepo's package manager) — or Node.js >=18 with npm if you only want this package
~1 GB free disk space for the ONNX model, which downloads automatically on first run

Clone the repository

git clone https://github.com/OpenSourceAGI/qwksearch-research-agent.git
cd qwksearch-research-agent/packages/extract-pdf-docling

Option 1 — Node.js / Hono API (recommended)

# From the monorepo root, install all workspace dependencies
cd qwksearch-research-agent
bun install

# Then run this package specifically
cd packages/extract-pdf-docling
bun run dev     # starts with --watch on http://localhost:3000
# or
bun run start   # production start

Using npm instead of Bun works the same way (npm install then npm run dev).

The first request triggers a download of the onnx-community/granite-docling-258M-ONNX model (cached locally afterward). Once running:

API docs (Swagger UI): http://localhost:3000/docs
OpenAPI spec: http://localhost:3000/openapi.json
Health check: http://localhost:3000/health
Convert endpoint: POST http://localhost:3000/api/v1/convert

See test/pdf.test.js for example client requests (URL, base64, and streaming conversion).

Deploying to Cloudflare Workers

A wrangler.jsonc config is included for deploying the API as a Cloudflare Worker:

npx wrangler dev      # local Workers runtime
npx wrangler deploy   # deploy to Cloudflare

Option 2 — Python / Docker (full Docling pipeline)

The pdf-to-html-docling-python/ subfolder contains a standalone FastAPI service using the actual ibm-granite/granite-docling-258M model via transformers + docling-core.

cd pdf-to-html-docling-python
docker compose up --build

This builds the image, installs PyTorch (CPU by default) and Docling dependencies, and starts the API on http://localhost:8000 (health check at /health).

To run it without Docker, using uv:

cd pdf-to-html-docling-python
uv sync
uv run python src/pdf-granite-docling.py --help

Configuration Options

The converter accepts several options when used programmatically:

// PDF to images conversion options
const imageOptions = {
  density: 150,        // DPI for image conversion
  format: 'png',       // Output format
  width: 1600,         // Max width
  height: 1600,        // Max height
  savePath: './temp'   // Temporary directory
};

const imagePaths = await converter.convertPDFToImages(pdfPath, imageOptions);

Output Features

The generated HTML includes:

Clean styling with modern CSS
Responsive design that works on mobile devices
Page separation with clear page headers
Structured content with proper headings and lists
Conversion metadata showing date and model used

Performance Notes

Processing time: Approximately 1-3 minutes per page (depending on content complexity)
Model: Uses the optimized mlx-bf16 variant for better performance
Image optimization: Automatically resizes images for optimal model processing
Retry logic: Handles model loading delays with automatic retries

Comparison: Docling vs Chandra vs Paddle OCR

Docling stands out for its emphasis on preserving semantic structure and producing highly accurate markdown or HTML outputs, making it particularly valuable for documents with complex layouts, tables, and formulas. Compared to Chandra OCR, Docling offers robust formula extraction with a specialized model and excels in maintaining layout/heading hierarchy for finance, legal, and scientific PDFs. However, Chandra surpasses Docling in overall extraction accuracy, especially for advanced table detection, handwriting, and multilingual documents, and is generally faster in batch scenarios due to efficient architecture and optional quantization. Chandra is thus preferred for large-scale, highly diverse datasets, while Docling is favored for projects that require deep structure recovery and granular content annotation.

When compared to PaddleOCR, Docling delivers superior structured output and semantic fidelity, ensuring table and figure relationships are retained in markdown/HTML even from complex scanned PDFs. PaddleOCR is renowned for its speed, scalability, and ease of deployment, which makes it ideal for rapid processing and commercial batches. However, PaddleOCR often produces less accurate table and layout segmentation, sometimes misaligning content from scientific papers or multi-column documents, whereas Docling’s transformer-based approach better preserves the source document’s logical flow and structure. PaddleOCR is an excellent choice for multilingual and quick turnaround applications, but Docling remains the go-to tool for projects where document detail and structured output are essential.

| Model | Made by | Size | License | Link | Release year | Accuracy | File size | Ease | Monthly cost | | -------------------- | -------------------- | --------------------: | ------------------- | ------------------------------------------------------------- | -----------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------: | ------ | ------------: | | Nanonets-OCR2–3B | Nanonets | 3–4B | Apache 2.0 | Hugging Face | 2025 | 78.56% ChartQA, 89.43% DocVQAhuggingface | ~6–12 GBhuggingface | Easy | $150–$500 | | PaddleOCR-VL | Baidu / PaddlePaddle | 0.9B | Open source | PaddleOCR | 2025 | 92.6 OmniDocBench v1.5atul4u.medium | ~2–4 GBhuggingface | Easy | $100–$400 | | dots.ocr | RedNote HiLab | 1.7B | MIT | Hugging Face | 2025 | EN edit distance 0.032, ZH 0.066huggingface | ~3–6 GBhuggingface | Medium | $150–$600 | | olmOCR-2 | Allen AI | 7B | Apache 2.0 | Project | 2025 | 0.875 GPT-4o alignment; +14.2 on olmOCR-Benchatul4u.medium | ~14–28 GBatul4u.medium | Medium | $300–$1,000 | | Granite-Docling-258M | IBM | 258M | Apache 2.0 | IBM on Hugging Face | 2025 | OCRBench 500; OCR F1 0.84atul4u.medium | ~0.5–1.5 GBatul4u.medium | Easy | $50–$250 | | DeepSeek-OCR | DeepSeek | 3B total, 570M active | MIT | Project | 2025 | 97% decoding precision at 10x compressionatul4u.medium | ~6–12 GBatul4u.medium | Medium | $250–$900 | | Chandra | datalab-to | ~3–7B | Modified OpenRAIL-M | Hugging Face | 2025 | Math 80.3, tables 88.0, tiny text 92.3atul4u.medium | ~6–14 GBatul4u.medium | Medium | $200–$800 | | Qwen3-VL | Alibaba / Qwen | 2B–235B | Apache 2.0 / Tongyi | Family | 2025 | Top-tier across OCRBench and related benchmarksatul4u.medium | ~4–470 GBatul4u.medium | Hard | $500–$3,000+ |