How to Configure pdf-inspector Processing Options: A Complete Guide

Configure pdf-inspector processing options using the PdfOptions builder, which exposes fluent methods for selecting processing mode, paginated extraction, password decryption, OCR, table detection, and markdown output formatting.

The pdf-inspector crate, developed by Firecrawl, provides a Rust-based PDF extraction pipeline with fine-grained configuration through builder-style APIs. Whether you're extracting markdown from encrypted documents, running lightweight analysis, or processing only specific pages, understanding how to configure pdf-inspector processing options is essential for optimizing both accuracy and performance.

Core Configuration: The PdfOptions Builder

All processing behavior in pdf-inspector stems from the PdfOptions struct defined in src/lib.rs. This struct implements a fluent builder pattern, allowing you to chain configuration methods for concise, readable setup.

The primary entry point is PdfOptions::new(), which returns a builder with sensible defaults. You then append methods to customize extraction:

use pdf_inspector::{PdfOptions, ProcessMode};

let opts = PdfOptions::new()
    .mode(ProcessMode::Extract)   // full markdown extraction
    .ocr(true)                    // enable Tesseract OCR
    .skip_tables(false);          // preserve table detection

Processing Modes Explained

The mode option controls the high-level operation performed on the PDF. This is defined in src/process_mode.rs as the ProcessMode enum with three variants:

Mode	Purpose	Typical Output
Extract	Full content extraction	Structured markdown with metadata
Analyze	Classification without full extraction	Document type, complexity score
Detect	Lightweight format detection	Binary yes/no for PDF characteristics

use pdf_inspector::{PdfOptions, ProcessMode};

// Run classification only
let analysis_opts = PdfOptions::new()
    .mode(ProcessMode::Analyze);

Page Selection and Document Access

For large PDFs, processing every page is often unnecessary. The pages method accepts a slice of zero-based page indices:

// Process only pages 1, 3, and 6 (display pages 2, 4, and 7)
let opts = PdfOptions::new()
    .pages([0, 2, 5]);

For encrypted documents, provide the password via the password method. If omitted, the file opens without decryption; an incorrect password raises an error:

let opts = PdfOptions::new()
    .password("document-secret");

Content Processing Flags

Several boolean flags fine-tune extraction behavior:

• ocr — Enables Tesseract OCR for scanned pages. Default: false
• skip_tables — Disables table-detection heuristics, returning raw text only. Default: false

// Optimize for speed on scanned documents without tables
let opts = PdfOptions::new()
    .ocr(true)
    .skip_tables(true);

These flags are processed in src/lib.rs around line 176, where the main pipeline orchestrates extraction stages based on your configuration.

Markdown Output Configuration

Fine-grained control over markdown formatting lives in MarkdownOptions, defined in src/markdown/mod.rs. This separate builder configures how extracted content renders:

Option	Controls	Default
include_images	Emit <img> tags for extracted images	false
include_links	Preserve hyperlink markup as [text](url)	true
profile	Select formatting style (Default, Compact, Verbose)	Default

use pdf_inspector::markdown::{MarkdownOptions, MarkdownProfile};

let md_opts = MarkdownOptions::default()
    .include_images(true)                 // embed image references
    .profile(MarkdownProfile::Compact);   // minimal whitespace

The MarkdownProfile affects line break density, heading depth translation, and list formatting verbosity—critical when downstream tools have specific whitespace requirements.

Complete Configuration Example

Combine PdfOptions and MarkdownOptions for full pipeline control:

use pdf_inspector::{PdfOptions, ProcessMode, MarkdownOptions, MarkdownProfile};

// Configure extraction behavior
let opts = PdfOptions::new()
    .mode(ProcessMode::Extract)
    .pages([0, 1, 2, 3, 4])      // first 5 pages only
    .password("encrypted-doc")
    .ocr(true)
    .skip_tables(false);

// Configure output formatting
let md_opts = MarkdownOptions::default()
    .include_images(true)
    .include_links(true)
    .profile(MarkdownProfile::Default);

// Execute with options
let result = pdf_inspector::process_pdf_with_options("report.pdf", opts);
println!("{}", result.markdown);

Python Bindings Configuration

The Python wrapper in src/python.rs exposes the same options through keyword arguments:

from pdf_inspector import PdfOptions, ProcessMode

opts = PdfOptions() \
    .mode(ProcessMode.Extract) \
    .pages([0, 3]) \
    .ocr(True)

md = process_pdf("document.pdf", opts)
print(md)

The Python layer constructs the underlying Rust PdfOptions struct, ensuring feature parity across languages.

CLI Configuration

Command-line usage maps directly to these options in src/bin/pdf2md.rs:

# Process specific pages with OCR enabled

pdf2md input.pdf --pages 0,1,2 --ocr --password secret -o output.md

# Compact formatting without images

pdf2doc input.pdf --profile compact --no-images

Summary

• PdfOptions in src/lib.rs is the central configuration struct for all pdf-inspector processing options
• Processing modes (Extract, Analyze, Detect) determine pipeline depth and output type
• Page selection, password decryption, and OCR are configured via fluent builder methods
• MarkdownOptions in src/markdown/mod.rs controls output formatting independently
• Both Rust and Python APIs maintain identical configuration capabilities
• The CLI in src/bin/pdf2md.rs exposes all options as command-line flags

Frequently Asked Questions

How do I process only the first page of a PDF?

Use the pages method with a single-element slice: PdfOptions::new().pages([0]). Pages are zero-indexed, so [0] selects the first page. Pass multiple indices like [0, 2, 4] for non-contiguous selection.

Can pdf-inspector handle password-protected PDFs?

Yes. Call .password("your-password") on the PdfOptions builder. The password is passed to the underlying PDF parser; an incorrect password results in a decryption error rather than silent failure.

What's the difference between Analyze and Extract modes?

ProcessMode::Analyze runs a lightweight classification that returns document metadata and complexity scores without full content extraction. ProcessMode::Extract performs the complete pipeline including layout analysis, table detection, and markdown generation. Choose Analyze for batch triage, Extract for content consumption.

How do I disable image extraction in the markdown output?

Set include_images to false in MarkdownOptions. By default, images are excluded (include_images: false). To embed image references, explicitly call .include_images(true) on your MarkdownOptions instance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}