How to Process Only Specific Pages of a PDF with pdf-inspector

To extract specific pages from a PDF using pdf-inspector, configure the pages field in PdfOptions when calling process_pdf_with_options, or pass the --pages flag to the pdf2md CLI.

The pdf-inspector library from Firecrawl provides precise control over PDF extraction through its configuration structs. When you need to process only specific pages of a PDF with pdf-inspector, you can leverage the pages vector to filter content before conversion to Markdown or JSON, avoiding the overhead of parsing unwanted pages.

Programmatic Page Selection with PdfOptions

The core mechanism resides in src/lib.rs, where the PdfOptions struct exposes a pages field. This field accepts a Vec<u32> containing 1-based page numbers that instruct the extractor to skip all other pages during processing.

When calling process_pdf_with_options, instantiate PdfOptions and populate the pages vector with your target indices:

use pdf_inspector::{process_pdf_with_options, PdfOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Specify exact pages to extract (1-based indexing)
    let opts = PdfOptions::new()
        .pages(vec![2, 4, 5]);

    let result = process_pdf_with_options("document.pdf", opts)?;
    println!("{}", result.markdown);
    Ok(())
}

Internally, the extraction logic in src/extractor/mod.rs checks this filter before processing each page, ensuring only the specified content reaches the output pipeline.

CLI Page Filtering with pdf2md

For command-line usage, the pdf2md binary defined in src/bin/pdf2md.rs exposes a --pages argument. The parser converts comma-separated values and range expressions—such as 1-3,5—into the Vec<u32> expected by PdfOptions.

Execute selective extraction via:

# Extract a single page

pdf2md --pages 7 report.pdf

# Extract pages 1 through 3 plus page 9

pdf2md --pages 1-3,9 report.pdf > excerpt.md

This CLI implementation builds the same PdfOptions struct used in the library API, maintaining consistent behavior across interfaces.

How Page Filtering Works Under the Hood

The page restriction logic operates at the orchestration layer within the extractor. When process_pdf_with_options receives a PdfOptions instance with the pages field populated, the engine iterates only over the specified indices instead of the full document range. This early filtering prevents resource-intensive parsing operations on excluded pages, significantly improving performance for large documents when you need only specific sections.

Summary

• PdfOptions.pages: Pass a Vec<u32> of 1-based page numbers to process_pdf_with_options in src/lib.rs to limit extraction programmatically.
• CLI convenience: The pdf2md binary in src/bin/pdf2md.rs accepts --pages with comma-separated values or ranges (e.g., 2-4,7).
• Performance benefit: Page filtering occurs early in the extraction pipeline, preventing unnecessary parsing of skipped content.
• Consistent behavior: Both Rust and CLI interfaces leverage the same underlying validation logic in src/extractor/mod.rs.

Frequently Asked Questions

How do I specify page ranges in the pdf-inspector CLI?

The pdf2md CLI supports range expressions within the --pages flag. Specify ranges with a hyphen and separate multiple selections with commas, such as --pages 1-3,5,8-10. The parser in src/bin/pdf2md.rs expands these ranges into individual page numbers before constructing the PdfOptions struct.

Can I process non-consecutive pages with the Rust API?

Yes. The pages field in PdfOptions accepts any Vec<u32>, allowing you to specify arbitrary, non-sequential page orders. For example, vec![1, 5, 10, 12] extracts only those specific pages regardless of their position in the document.

What happens if I provide an invalid page number?

The extractor validates page numbers against the total page count during processing. If the pages vector contains a number exceeding the document's length, the operation returns an error indicating the requested page is out of bounds.

Is page indexing 0-based or 1-based in pdf-inspector?

pdf-inspector uses 1-based indexing for the pages vector, matching standard document conventions where the first page is page 1. When constructing PdfOptions or using the --pages CLI flag, always reference pages starting at 1.

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