ProcessMode::Full vs Analyze vs DetectOnly in pdf-inspector: 3 Pipeline Modes Explained

ProcessMode::DetectOnly runs only PDF type detection (fastest), ProcessMode::Analyze adds text extraction and layout analysis, and ProcessMode::Full includes the complete pipeline with Markdown conversion.

The pdf-inspector library from Firecrawl uses a Rust enum called ProcessMode to control how deeply a PDF is processed. Located in [src/process_mode.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs), this enum lets you optimize for speed, flexibility, or completeness depending on your use case.

What ProcessMode::DetectOnly Does

ProcessMode::DetectOnly is the minimal processing tier. It runs only the fast PDF-type detector and skips all text extraction, layout analysis, and Markdown generation.

According to the source code, this mode:

• Returns PDF type (text-based, scanned, image-based, or mixed)
• Provides page count and processing time
• Avoids expensive extraction and rendering operations

Use this mode when you need to decide whether OCR is required before committing to full processing. For example, a document ingestion pipeline might filter out image-only PDFs or route them to specialized handlers.

pdf2md myfile.pdf --detect-only --json

What ProcessMode::Analyze Does

ProcessMode::Analyze expands the pipeline to include text extraction and layout analysis while skipping Markdown conversion.

In [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs), this mode:

• Calls detector::detect_type for PDF classification
• Invokes extractor::extract_text_with_positions_pages to pull positioned text items
• Runs detector::analyze_layout to compute structural complexity (tables, columns)
• Does not call markdown::convert

This mode suits applications that need raw extracted text with structural metadata for custom downstream processing. If you're building your own formatter or feeding data into a specialized analysis system, Analyze avoids the overhead of Markdown rendering you don't need.

pdf2md myfile.pdf --analyze --json

What ProcessMode::Full Does

ProcessMode::Full (the default) executes the complete pipeline: detection, extraction, layout analysis, and Markdown conversion.

The library proceeds through all stages and ultimately invokes markdown::convert from [src/markdown/convert.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs) to generate the final output. This is the standard mode for end-users who want a ready-to-use Markdown representation of any PDF.

pdf2md myfile.pdf --json       # JSON output with markdown field

pdf2md myfile.pdf               # Human-readable output

How the Mode Selection Works

The CLI entry point in [src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) maps command-line flags to enum variants:

let process_mode = if detect_only {
    ProcessMode::DetectOnly
} else if analyze {
    ProcessMode::Analyze
} else {
    ProcessMode::Full
};

The selected mode is then passed into the core library via PdfOptions::new().mode(process_mode) per lines 17-18 of the same file. The internal pipeline branches based on this setting, executing only the operations required for each tier.

Performance and Use Case Comparison

Mode	CLI Flag	Stops After	Best For
DetectOnly	--detect-only	PDF type detection	Quick classification, OCR routing decisions
Analyze	--analyze	Layout analysis (no Markdown)	Custom processing pipelines, raw text + structure
Full	(none, default)	Markdown conversion	Standard Markdown extraction

Summary

• ProcessMode::DetectOnly provides the fastest results with minimal overhead, returning only PDF metadata and type classification.

• ProcessMode::Analyze returns positioned text and layout complexity without Markdown rendering, ideal for downstream custom processing.

• ProcessMode::Full runs the complete pipeline including Markdown generation, serving as the default for standard use cases.

• The mode selector lives in [src/process_mode.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs), with CLI mapping in [src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) and mode-specific execution branching in [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs).

Frequently Asked Questions

What is the default ProcessMode if I don't specify a flag?

ProcessMode::Full is the default. As implemented in [src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs), the CLI falls through to ProcessMode::Full when neither --detect-only nor --analyze is provided.

Can I use ProcessMode::Analyze to get table structures without Markdown?

Yes. ProcessMode::Analyze specifically runs detector::analyze_layout which computes layout complexity including tables and columns, then stops before markdown::convert. This gives you structured data without rendered Markdown overhead.

How much faster is DetectOnly compared to Full?

ProcessMode::DetectOnly stops immediately after detector::detect_type, avoiding all text extraction and rendering operations. While exact speedup depends on PDF size and complexity, it typically executes in milliseconds versus seconds for full processing of large documents.

Where is the ProcessMode enum defined in the source code?

The ProcessMode enum is defined in [src/process_mode.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs) at lines 3-11, containing the three variants Full, Analyze, and DetectOnly.

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