version: "1.0.0" name: ask-extract-pdf description: Guide to extract-pdf (packages/extract-pdf), the PDF-to-structured-HTML converter — convertPDFToHTML() and its two independent switches, method (ts-block-algorithm / liteparse / liteparse-wasm) and processor (frontend / hybrid / docling / a processor URL), the Granite Docling OCR path and its optional dependencies, the page-scan heuristics, and the bundled Hono OCR server. Use when a PDF converts to empty or mangled HTML, when headings/lists/code blocks come out wrong, when scanned or table-heavy pages need OCR, or when the package fails to load in Cloudflare Workers or the browser.

Working With extract-pdf

packages/extract-pdf, published as extract-pdf. Converts a PDF URL or buffer into HTML with real structure — headings inferred from text-height statistics, lists, footnotes linked to their anchors, code and quote blocks, repeated headers removed, and each page number preserved in an invisible <i>. Slim by default: PDF.js is loaded at runtime from the pdfjs-serverless CDN build, so it works in Node, Cloudflare Workers and browsers. Options table: API.md.

Setup

import { convertPDFToHTML } from "extract-pdf";
const html = await convertPDFToHTML("https://example.com/paper.pdf");
const html2 = await convertPDFToHTML(await fs.readFile("paper.pdf"));

The only runtime dependency is grab-url. Everything OCR-related (@huggingface/transformers) and both LiteParse engines (@llamaindex/liteparse, @llamaindex/liteparse-wasm) are optional — install them only if you select that path.

Two independent switches

method chooses the parser; processor chooses where OCR happens. They are not alternatives to each other.

Setting method: "liteparse" short-circuits the whole file: the processor, ocrScanOptions and doclingOptions options are forwarded to LiteParse rather than driving this package's OCR path.

Picking the right call

Recipes

Point at your own OCR service. Deploy server/ (it has its own wrangler.jsonc), or docling-space/ as a Hugging Face Docker Space, then pass processor: "https://…" or processorUrl. The client POSTs base64 page images to {processorUrl}/api/v1/convert-base64; auth headers go in doclingOptions.processorHeaders (the Space wants X-Docling-Token, plus Authorization: Bearer hf_… when it is private).

Answer fast, OCR later. "hybrid" waits for every flagged page. For an instant result, run "frontend", return its HTML, and OCR ocrScan.pagesNeedingOcr afterwards. The live demo in site/ (components/demo/PdfDemo.tsx with worker/api.ts) does this: Workers have no canvas, so the browser rasterizes the flagged pages and the Worker forwards each image to the Space.

Tune the hybrid scan. ocrScanOptions (see ScanPagesForOCROptions) sets the thresholds that decide "this page looks like a figure/table". Widen them before reaching for full "docling" — OCR'ing every page is the expensive option.

Tune the model. doclingOptions: prompt (default "Convert this page to docling."), maxTokens (default 4096), scale (default 2, i.e. 144 DPI).

Troubleshooting