Struct DocumentConverter 

pub struct DocumentConverter { /* private fields */ }

Routes a SourceDocument to the backend for its format and returns a ConversionResult.

The Rust analogue of docling.document_converter.DocumentConverter. In Phase 0 the format→backend dispatch is a direct match; the Python notion of per-format FormatOption (backend + pipeline + options) arrives with the PDF/ML pipeline in a later phase.

Implementations

impl DocumentConverter

pub fn convert_archive<R: Read + Seek>( &self, reader: R, ) -> Result<ArchiveConversion<'_, R>, ConversionError>

Convert every document inside a ZIP archive (#557), one at a time: a lazy iterator of each entry’s ArchiveOutcome in directory order. Entries convert with this converter’s settings; the archive limits come from DocumentConverter::archive_limits. Errors only when reader is not a ZIP archive.

impl DocumentConverter

pub fn new() -> Self

A converter that accepts every supported format.

pub fn with_allowed_formats( formats: impl IntoIterator<Item = InputFormat>, ) -> Self

A converter restricted to an explicit set of formats. Sources of any other format are rejected with ConversionError::UnsupportedFormat.

pub fn page_range(self, first: usize, last: usize) -> Self

Convert only PDF pages first..=last (1-based inclusive, the page numbers a viewer shows — issue #80’s --pages A-B). Out-of-window pages are skipped before rasterization, so converting 3 pages of a 500-page PDF costs 3 pages. last clamps to the document; a window that selects no pages at all errors at convert time. Non-PDF formats ignore the window (they convert whole).

pub fn document_timeout(self, timeout: Option<Duration>) -> Self

A wall-clock budget per document for the PDF pipeline — docling’s PipelineOptions.document_timeout (#497); None = unlimited, the default. The budget starts with the conversion and is checked between pages: once spent, no further page is rendered or processed, the pages already finished become the document, and the result is a ConversionStatus::PartialSuccess carrying one ErrorItem (document_backend / pipeline, “document timeout of Ns exceeded after D of S pages …”). A page in flight finishes first, so a budget shorter than one page’s work still yields that page. Only the paginated pipeline has pages to stop between: declarative formats (Office, HTML, …) convert whole, as in docling, and a single image is never cut. A streaming conversion emits the pages that fit and ends with ConversionError::Timeout as its last item.

pub fn ocr_lang(self, lang: impl Into<String>) -> Self

OCR recognition language for scanned PDF/image pages: "en" (the default — English PP-OCRv3, proper Latin word spacing) or "ch" (the multilingual model docling conformance is measured with — glues Latin words). An unknown value warns at conversion time and uses the default; explicit DOCLING_OCR_REC_ONNX/DOCLING_OCR_DICT paths win over this switch. Under ocr_engine tesseract it is Tesseract’s language list instead — tessdata stems ("deu", "eng+fra", "script/Cyrillic") or BCP-47 tags mapped onto them ("de", "zh-Hant"), see docling_pdf::tesseract_lang_arg; en and ch keep working there. Formats that never OCR ignore it.

pub fn artifacts_dir(self, dir: impl Into<String>) -> Self

Where ImageMode::Referenced streaming writes image files, and the link prefix used in the Markdown (default artifacts, matching the buffered export’s convention). Relative paths resolve against the process working directory.

pub fn encoding(self, label: Option<String>) -> Self

Decode text inputs (Markdown, CSV, AsciiDoc, WebVTT, LaTeX, the XML dialects, …) with this character encoding instead of detecting one — docling’s TextBackendOptions.encoding (MarkdownBackendOptions(encoding="shift_jis")). A WHATWG encoding label (shift_jis, koi8-r, windows-1251, latin1; Python codec spellings with _ are accepted). Nothing is guessed: bytes the encoding cannot decode fail the conversion, as does an unknown label. None (default) detects — a byte-order mark, then UTF-8, then windows-1252 (see SourceDocument::text). A source that already carries its own SourceDocument::encoding keeps it.

pub fn archive_limits(self, limits: ArchiveLimits) -> Self

The converter’s encoding applied to a source that did not set its own. Bounds on what a ZIP input may make the converter decompress (#557): entries considered, per-entry and total uncompressed size, compression ratio. ArchiveLimits::default when not set. Only DocumentConverter::convert_archive reads them.

pub fn video_frames(self, max: usize) -> Self

Cap the number of frames sampled from a video (#138 Phase 2); 0 disables frame extraction entirely (Phase 1 behavior: transcript only). Defaults to DEFAULT_VIDEO_FRAMES. Frames are extracted with the ffmpeg binary when present (DOCLING_FFMPEG overrides the path); without it a video converts to its transcript alone.

pub fn xbrl_taxonomy(self, dir: impl Into<PathBuf>) -> Self

The folder holding the taxonomy an XBRL instance refers to (docling’s XBRLBackendOptions.taxonomy): the filing’s extension schema and linkbases at the relative paths its link:schemaRef names, plus any taxonomy packages (.zip with a META-INF/catalog.xml) that map the base taxonomies’ http(s) URLs to files for offline use. Without it the instance’s own directory is searched. Nothing is fetched remotely; a document that cannot be found only costs the fact graph the hierarchy it would have contributed.

pub fn asr_model(self, model: Option<String>) -> Self

Select a named ASR model preset for audio sources — the English-only (whisper_tiny_en, whisper_base_en, whisper_small_en) and Distil-Whisper (whisper_distil_small_en) variants of docling’s ASR model specs, or parakeet_tdt_0.6b_v3 (NVIDIA’s Parakeet TDT 0.6B v3 transducer, 25 European languages detected by the model, #508 — see docling_asr::parakeet). None (default) uses Whisper tiny (multilingual) from .models/asr/; presets load from .models/asr/<preset>/ (fetch them with download_dependencies.sh --asr-model=<preset>).

pub fn asr_lang(self, lang: Option<String>) -> Self

Select the ASR transcription language for audio/video sources: a Whisper code (en, de, zh, …) or auto. None (default) falls back to DOCLING_RS_ASR_LANG, and — when that is unset too — to per-file auto-detection from the first 30-second window (docling 2.116 parity). English-only presets always transcribe English.

pub fn strict(self, strict: bool) -> Self

Select the Markdown export mode for documents this converter produces.

false (default) makes crate::DoclingDocument::export_to_markdown reproduce docling’s legacy output byte-for-byte; true makes it emit cleaner, more conformant Markdown (code-fence languages preserved, no inline-run spacing artifacts, no entity re-escaping). Rust-only — Python docling has no such switch.

pub fn fetch_images(self, fetch: bool) -> Self

Fetch and embed external <img> images for HTML/EPUB/MHTML/JATS sources.

Off by default (matching docling’s enable_*_fetch=False), so output is unchanged unless you opt in. When on, the HTML/EPUB/MHTML backends resolve each <img src> — data: URIs, local files (relative to the source file’s directory), http(s) URLs, and EPUB/MHTML archive entries — and the JATS backend reads a <fig>’s <graphic xlink:href> from the source file’s directory (#392), embedding the bytes so they survive into JSON ImageRefs and crate::DoclingDocument::export_to_markdown_with_images.

Remote http(s) URLs are fetched over the network; enable only for input you trust (it can otherwise be used to make the process issue requests).

pub fn list_attachments(self, list: bool) -> Self

Append an Attachments section to converted emails (.eml / .msg): one list item per attachment, name (content/type) — names and types only, the payload is never embedded. docling’s opt-in EmailBackendOptions.list_attachments (#251); off by default.

pub fn skip_empty_cells(self, skip: bool) -> Self

Omit empty cells from sparse spreadsheet table grids (#271; XLSX/XLS family, opt-in — a docling.rs extension, docling materialises the full bounding box). A ragged region’s box is mostly padding on sparse sheets (~7× output inflation); with this on, each row keeps only its occupied cells (merge-covered continuations included) and a table that loses cells drops its span/structure overlay. Off by default — default output stays byte-for-byte docling.

pub fn compact_tables(self, compact: bool) -> Self

Emit Markdown tables in the compact | a | b | / | - | - | form instead of docling-core’s width-padded GitHub serializer (#271, all formats; opt-in — a docling.rs extension). On sparse spreadsheets the padding dominates the output size; compact rendering keeps the grid semantics and drops only whitespace. Off by default — default output stays byte-for-byte docling.

pub fn page_break_placeholder(self, placeholder: Option<String>) -> Self

Insert placeholder between pages in the Markdown export — docling’s export_to_markdown(page_break_placeholder=…) (docling-core’s MarkdownParams, docling-serve’s md_page_break_placeholder). Where docling marks a break between two items whose prov.page_no differ, the serializer here marks it between two rendered blocks separated by a page boundary — the PageInfo marker opening every PDF page and sheet, the PageBreak between slides and DjVu / DocTags pages — so a break never leads or trails the document and empty pages collapse into one. None (the default) keeps Markdown free of page breaks, as docling’s default export is. Markdown only; JSON carries pages in prov.

pub fn finish_document(&self, document: &mut DoclingDocument)

The document-level settings convert applies to every backend’s output: the serializer knobs carried on the document (strict, compact_tables, page_break_placeholder) so each later Markdown export agrees, and first-class cells for every table. Public for callers that run a backend themselves — docling-serve converts PDFs and images on a warm Pipeline and finishes them here, so a request’s options reach them as they reach every other format (#547).

pub fn ebcdic_layout(self, layout: impl Into<String>) -> Self

The copybook layout for EBCDIC sources (#252): docling’s EbcdicLayout JSON, inline (a string starting with {) or as a file path. Without it, a path-loaded source looks for a <stem>.layout.json sidecar; converting EBCDIC with neither is an error — the bytes are meaningless without their copybook.

pub fn ebcdic_layout_opt(self, layout: Option<String>) -> Self

Option-typed variant of ebcdic_layout for call sites plumbing an optional flag through (None keeps the sidecar fallback).

pub fn no_table_former(self, disable: bool) -> Self

Skip loading and running the TableFormer table-structure model for PDF/image/METS sources.

Off by default. When enabled, table regions are still detected and emitted, but their structure is reconstructed geometrically from cell positions instead of the ONNX model’s predicted structure — no model load and no per-table inference, at the cost of table fidelity. Useful when parsing speed matters more than exact table structure, especially with convert_streaming.

pub fn no_text_panels(self, disable: bool) -> Self

PDF/image: keep every detected picture as a picture — disable the text-panel demotion that turns an uncaptioned, dense text-panel “picture” into paragraphs (#157). The escape hatch for image-extraction workflows and for charts the heuristic might still misjudge on scanned pages (#173).

pub fn heading_hierarchy(self, enable: bool) -> Self

Infer PDF/image section-header levels after assembly (#302, docling’s HeadingHierarchyModel with its default options): the PDF outline (bookmarks) is authoritative, legal/outline numbering covers headings without a bookmark match, and font size/weight/slant/case rank the rest. Off by default (docling parity): every detected heading then keeps the flat level the assembler emits. Non-PDF/image formats ignore it (their backends carry real heading levels already).

pub fn no_ocr(self, disable: bool) -> Self

Skip layout detection, OCR, and TableFormer entirely for PDF/image/METS sources — no model load, no inference of any kind.

Off by default. When enabled, the PDF’s embedded text cells are grouped by line and emitted as plain paragraphs in reading order: no headings, lists, tables, code blocks, or pictures, since that structure comes from the layout model. The fastest possible PDF path, but pages with no embedded text layer (scanned/image-only PDFs) yield no text at all — convert those without this flag. Implies no_table_former.

pub fn skip_ocr(self, disable: bool) -> Self

Never run OCR, but keep layout detection and TableFormer — docling’s independent do_ocr=False (#244), the counterpart of no_table_former. Unlike no_ocr (the skip-everything fast path), structured output — headings, tables, pictures, reading order — is preserved; only text that exists solely as pixels is lost (scanned pages come back with empty regions, and the speculative OCR of large embedded images never runs). The OCR model is never loaded, and independently of this flag a missing OCR model now degrades to the same behavior with a warning instead of failing the conversion. SVG inputs route to direct <text> extraction (their text is native — skipping OCR must not lose it), like no_ocr.

pub fn force_full_page_ocr(self, force: bool) -> Self

OCR every PDF page from its rendered image even when the page carries an embedded text layer — docling’s force_full_page_ocr. The escape hatch for text layers that exist but lie (broken encodings, subset fonts with garbage mappings, scanned forms with a few typed-in fields). Off by default; ignored when no_ocr is set, mirroring docling, where it is a sub-option of do_ocr. Applies to PDFs only — standalone images are always OCR’d.

pub fn ocr_mode(self, mode: impl Into<String>) -> Self

Which document regions feed the OCR — docling’s OcrMode (#254): default, full_page, layout_regions, or pdf_aware_layout_regions. The default is the text-layer-aware behavior (docling’s pdf_aware_layout_regions); full_page/layout_regions discard the text layer like force_full_page_ocr — see docling_pdf::OcrMode for the mapping. An unknown value warns at conversion time and uses the default. PDF/image ML pipeline only.

pub fn ocr_engine(self, engine: impl Into<String>) -> Self

Which OCR engine recognizes text on scanned pages (#460): "ppocr" (the default — the built-in PP-OCRv3 recognizer, the conformance engine) or "tesseract" (the system tesseract binary, docling’s TesseractCliOcrOptions; needs tesseract-ocr with a language pack installed — DOCLING_TESSERACT names the binary, DOCLING_RS_TESSERACT_PSM its page segmentation mode, DOCLING_RS_TESSDATA_DIR / TESSDATA_PREFIX its data). Both read the same layout-region crops; ocr_lang is the engine’s language. An unknown value warns at conversion time and uses the default (DOCLING_RS_OCR_ENGINE, else PP-OCR). Formats that never OCR ignore it.

pub fn ocr_scale(self, scale: f32) -> Self

OCR render scale in pixels per PDF point — docling’s OcrOptions.scale (#254; docling’s default 3 = 216 dpi). Unset feeds the recognizer the pipeline’s own 2.0 px/pt page render; a different value resamples that render for the OCR input only, leaving layout and TableFormer pixels untouched. Non-positive values warn at conversion time and are ignored. PDF/image ML pipeline only.

pub fn images_scale(self, scale: f32) -> Self

Pixels per PDF point for picture crops and page images — docling’s images_scale (#520). Unset delivers crops at the pipeline’s own 2.0 px/pt render (144 dpi), as before; another value resamples it (above 2.0 that upsamples, it does not re-render). The picture’s dpi in the JSON export is 72·scale either way (#519). Non-finite or non-positive values are ignored. PDF/image ML pipeline only.

pub fn generate_page_images(self, enabled: bool) -> Self

Keep every page’s render as a page image — docling’s generate_page_images (#520): the JSON export carries it as pages[n].image at Self::images_scale, which docling-core’s TableItem.get_image / FormulaItem.get_image crop from. Off by default (one full-page PNG per page in memory). PDF/image ML pipeline only; text-layer-only (no_ocr) and streaming conversions get none.

pub fn do_picture_classification(self, enable: bool) -> Self

Classify each detected picture with the DocumentFigureClassifier model (docling’s do_picture_classification). Off by default.

The full 26-class prediction distribution (bar_chart, logo, signature, …) lands on the picture item and is serialized into the docling JSON as the classification annotation plus the meta.classification field. Markdown output is unaffected. Needs .models/picture_classifier.onnx (fetched by scripts/install/download_dependencies.sh); a missing model warns once and skips classification.

pub fn do_code_enrichment(self, enable: bool) -> Self

Rewrite detected code blocks with the CodeFormulaV2 VLM (docling’s do_code_enrichment). Off by default.

The model re-reads the code crop at ~120 dpi, emits the clean source text (line breaks included) and identifies the language, which lands in the JSON code_language field. Needs the .models/code_formula/ graphs (fetched by scripts/install/download_dependencies.sh); a missing model warns once and leaves the block as extracted.

pub fn do_formula_enrichment(self, enable: bool) -> Self

Decode display formulas to LaTeX with the CodeFormulaV2 VLM (docling’s do_formula_enrichment). Off by default.

An enriched formula renders as $$latex$$ in Markdown and as a formula text item in the JSON, replacing the <!-- formula-not-decoded --> placeholder. Same model artifacts as do_code_enrichment.

pub fn use_web_browser(self, enable: bool) -> Self

Pre-render HTML-routing input in a headless browser before parsing.

Off by default. When enabled, HTML sources — and MHTML/EPUB, which assemble HTML from their archives — are loaded in the system Chromium (driven from Rust over the DevTools protocol — no Node/Playwright) so the CSS cascade is resolved: elements the browser computes as display:none (e.g. a stylesheet-collapsed nav menu) are removed before the normal HTML backend runs. This is the one behaviour a pure-Rust parse can’t reproduce; everything else (structure, tables, KVP, formatting) is still handled in Rust on the cleaned HTML.

Requires the crate’s web-browser Cargo feature; without it, converting an HTML source with this enabled returns ConversionError::Browser.

pub fn convert_streaming( &self, source: SourceDocument, ) -> Result<MarkdownStream, ConversionError>

Convert a source document to Markdown incrementally, returning an iterator of Markdown chunks (with picture placeholders).

Concatenating every Ok chunk reproduces convert(...).document.export_to_markdown() byte-for-byte. The win is for PDF, whose pages are processed in parallel: each page’s Markdown is emitted in document order as soon as it is ready, so output starts before the whole document is converted. Other formats build their document up front and stream it through the same interface.

Streaming is Markdown-only — JSON needs the whole node tree, so there is no streaming JSON. The conversion runs on a background thread; dropping the returned MarkdownStream cancels it.

pub fn convert_streaming_images( &self, source: SourceDocument, image_mode: ImageMode, ) -> Result<MarkdownStream, ConversionError>

Like convert_streaming but with an explicit picture ImageMode.

ImageMode::Referenced streams too (issue #80): each page’s images are written to artifacts_dir as the page’s Markdown is emitted and dropped from memory, so an image-heavy PDF holds ~one page of images at a time instead of all of them until export. The chunks and files match the buffered export_to_markdown_with_images(ImageMode::Referenced, ..) output.

pub fn convert( &self, source: SourceDocument, ) -> Result<ConversionResult, ConversionError>

Convert a single source document.

The source converts as its declared format (the extension’s). Only if that fails is the content inspected: when it is evidently another format — RTF, an OOXML / ODF / EPUB package, an OLE Word / Excel / PowerPoint / Outlook file, PDF or HTML saved under the wrong extension (#556) — the conversion is retried once as that format, and the result reports the format it was converted as. A document that converts as declared is never inspected; when the retry fails too, or nothing is recognised, the first attempt’s error stands.

impl DocumentConverter

pub fn convert_email_attachments( &self, bytes: &[u8], ) -> Result<EmailAttachmentConversion<'_>, ConversionError>

Convert every attachment of an .eml / .msg (#561), one at a time: a lazy iterator of each attachment’s ArchiveOutcome in message order. Attachments convert with this converter’s settings and are bounded by its archive_limits. Errors only when bytes is not a message.

impl DocumentConverter

pub fn from_options(options: &ConvertOptions) -> Result<Self, OptionsError>

A converter configured from ConvertOptions — validated and applied onto the defaults (ConvertOptions::apply on Self::new).

Trait Implementations

impl Clone for DocumentConverter

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DocumentConverter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DocumentConverter

fn default() -> Self

Returns the “default value” for a type.