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

Use the PdfOptions fluent builder to control extraction mode, page ranges, passwords, and OCR, while MarkdownOptions manages image embedding, link preservation, and formatting profiles.

The firecrawl/pdf-inspector Rust crate provides a type-safe configuration API centered around the PdfOptions struct. To configure pdf-inspector processing options programmatically, you chain builder methods that modify extraction behavior before passing the final struct to process_pdf_with_options().

Core Configuration with PdfOptions

The PdfOptions struct, defined in src/lib.rs at line 176, implements a consuming builder pattern. Each method returns Self, enabling fluent configuration of the PDF pipeline.

Processing Modes

The mode option accepts a ProcessMode enum variant, defined in src/process_mode.rs, that determines the high-level operation:

• ProcessMode::Extract – Runs the full pipeline, converting PDF content to markdown with layout preservation (default).
• ProcessMode::Analyze – Classifies the PDF structure and metadata without generating full markdown output.
• ProcessMode::Detect – Performs lightweight content detection for quick inspection.

use pdf_inspector::{PdfOptions, ProcessMode};

let opts = PdfOptions::new()
    .mode(ProcessMode::Analyze);  // Classification only

Page Selection and Password Protection

For encrypted documents or partial extraction, use the pages and password options:

• pages – Accepts a slice of 0-based page numbers. Omitting this processes all pages.
• password – Supplies the decryption key for password-protected PDFs. An incorrect password returns an error.

let opts = PdfOptions::new()
    .pages([0, 2, 4])           // Process pages 1, 3, and 5
    .password("secret");          // Decrypt before processing

Table Detection and OCR Settings

Control heuristic engines with boolean flags:

• skip_tables – When true, disables table-detection heuristics in src/lib.rs, returning raw text only.
• ocr – When true, enables Tesseract-based OCR for scanned pages via the embedded engine.

let opts = PdfOptions::new()
    .skip_tables(true)            // Ignore table structures
    .ocr(true);                    // Enable text recognition

Fine-Tuning Markdown Output with MarkdownOptions

When ProcessMode::Extract is active, the pipeline uses MarkdownOptions, implemented in src/markdown/mod.rs at line 921, to control output formatting.

Image and Link Handling

Two boolean flags govern markdown content:

• include_images – Emits <img> tags for detected images (default: false).
• include_links – Preserves hyperlink markup as [text](url) (default: true).

use pdf_inspector::MarkdownOptions;

let md_opts = MarkdownOptions::default()
    .include_images(true)
    .include_links(false);

Markdown Profiles

The profile option selects a MarkdownProfile variant that affects whitespace, heading depth, and list formatting:

• MarkdownProfile::Default – Balanced formatting with standard line breaks.
• MarkdownProfile::Compact – Minimal whitespace for dense output.
• MarkdownProfile::Verbose – Explicit structural markers for debugging.

let md_opts = MarkdownOptions::default()
    .profile(MarkdownProfile::Compact);

Complete Configuration Examples

Chain all options to tailor the extraction pipeline. The Python bindings in src/python.rs at line 485 mirror the Rust API.

Rust Implementation

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

let opts = PdfOptions::new()
    .mode(ProcessMode::Extract)
    .pages([1, 2, 5])
    .password("my-pdf-pw")
    .skip_tables(true)
    .ocr(true);

let md_opts = MarkdownOptions::default()
    .include_images(true)
    .profile(MarkdownProfile::Compact);

let result = pdf_inspector::process_pdf_with_options("example.pdf", opts);
println!("{}", result.markdown);

Python Bindings

from pdf_inspector import PdfOptions, ProcessMode

opts = PdfOptions().mode(ProcessMode.Extract).pages([0, 3])
md = process_pdf("example.pdf", opts)
print(md)

The CLI driver at src/bin/pdf2md.rs demonstrates command-line argument parsing that ultimately constructs these same structs.

Summary

• Configure pdf-inspector processing options through the PdfOptions builder defined in src/lib.rs.
• Set the mode to Extract, Analyze, or Detect depending on whether you need markdown output, classification, or lightweight detection.
• Limit processing to specific pages (0-based indices) or supply a password for encrypted files.
• Enable ocr for scanned documents and skip_tables to bypass table heuristics.
• Use MarkdownOptions to control image tags, hyperlink preservation, and formatting profiles (Default, Compact, Verbose).

Frequently Asked Questions

What is the default processing mode in pdf-inspector?

The default mode is ProcessMode::Extract, which runs the full extraction pipeline and generates markdown output. You can change this by calling .mode(ProcessMode::Analyze) or .mode(ProcessMode::Detect) on the PdfOptions builder in src/lib.rs.

How do I process only specific pages of a PDF?

Pass a slice of 0-based indices to the pages method: PdfOptions::new().pages([0, 2, 4]) processes the first, third, and fifth pages. If omitted, the extractor processes all pages in the document.

Can pdf-inspector handle encrypted PDFs?

Yes. Supply the decryption password using the password option: PdfOptions::new().password("secret"). If the password is incorrect or the PDF is encrypted and no password is provided, the library returns an error.

How do I enable OCR for scanned documents?

Set the ocr flag to true on your PdfOptions instance: PdfOptions::new().ocr(true). This activates the embedded Tesseract engine to recognize text in scanned or image-based pages.

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