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

> Master pdf-inspector processing options with the PdfOptions builder. Easily configure mode, pagination, decryption, OCR, tables, and markdown output for efficient document analysis.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/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:

```rust
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`](https://github.com/firecrawl/pdf-inspector/blob/main/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 |

```rust
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:

```rust
// 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:

```rust
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`

```rust
// 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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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` |

```rust
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:

```rust
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/python.rs) exposes the same options through keyword arguments:

```python
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs):

```bash

# 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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/mod.rs) controls output formatting independently
- Both Rust and Python APIs maintain identical configuration capabilities
- The CLI in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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.