# PDF-to-Markdown Conversion Options in pdf-inspector: Complete Configuration Guide

> Explore pdf-inspector's Markdown conversion options. Configure profiles, page numbers, images, and tables for precise PDF to Markdown transformation. Learn more.

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

---

**`pdf-inspector` exposes a `MarkdownOptions` struct with 8+ configurable fields—including profile presets, page numbering, image inclusion, and table formatting—to control how PDFs are converted to Markdown.**

The `pdf-inspector` Rust library provides granular control over PDF-to-Markdown conversion through its `MarkdownOptions` configuration system. Whether you're using the `pdf2md` CLI or embedding the library directly, understanding these options lets you optimize output for readability, token efficiency, or downstream LLM processing. This guide covers every field in the `MarkdownOptions` struct as defined in [`src/markdown/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/mod.rs) and shows how to apply them via CLI flags or programmatic API calls.

## MarkdownOptions Struct Overview

The `MarkdownOptions` struct lives in [`src/markdown/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/mod.rs) and serves as the central configuration object for all Markdown output. The `impl Default for MarkdownOptions` (lines 1263–1296) establishes sensible defaults, while the CLI in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) maps command-line flags to these fields.

### Core Configuration Fields

Each field directly influences how the conversion engine in [`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs) renders the final Markdown output.

| Field | Type | Default | Purpose |
|-------|------|---------|---------|
| `profile` | `MarkdownProfile` | `Standard` | Selects formatting preset: `Standard` for readability or `Compact` for token efficiency |
| `include_page_numbers` | `bool` | `false` | Emits `<pagenum>` headers before each page's content |
| `include_images` | `bool` | `false` | Inserts Markdown image syntax for extracted raster images |
| `include_tables` | `bool` | `true` | Renders detected tables as Markdown tables; disabled outputs raw cell text |
| `preserve_newlines` | `bool` | `true` | Retains original line breaks; `false` collapses them for LLM processing |
| `base_font_size` | `f32` | `12.0` | Calibrates relative heading detection; larger values reduce heading prominence |
| `skip_empty_pages` | `bool` | `true` | Omits pages with no extractable content from output |
| `use_code_fences` | `bool` | `true` | Wraps code blocks in triple backticks; `false` uses indentation style |

> **Note on `markdown_profile`:** This alias for `profile` exists for backward compatibility but should not be used in new code.

## Markdown Profiles: Standard vs. Compact

The `MarkdownProfile` enum defines two conversion presets that bundle multiple formatting decisions.

### Standard Profile

- Preserves blank lines for visual separation
- Maintains generous whitespace around headings and paragraphs
- Optimized for human reading and manual editing

### Compact Profile

- Removes most blank lines and trims excess spacing
- Minimizes token count for LLM context windows
- Selected via `--compact` CLI flag or `profile = MarkdownProfile::Compact`

## CLI Usage Examples

The `pdf2md` binary in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) exposes these options through intuitive flags.

### Basic Conversion with Defaults

```bash
pdf2md my-document.pdf

```

Uses all default `MarkdownOptions` values—suitable for general-purpose conversion.

### Compact Output with Page Numbers

```bash
pdf2md my-document.pdf --compact --page-numbers

```

Maps directly to:

```rust
let mut markdown = MarkdownOptions::default();
markdown.profile = MarkdownProfile::Compact;
markdown.include_page_numbers = true;

```

This configuration (lines 544–546 in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs)) is ideal when feeding PDF content into AI systems with limited context windows.

### Include Extracted Images

```bash
pdf2md my-document.pdf --include-images

```

Sets `markdown.include_images = true`. Tables remain enabled by default since `include_tables` defaults to `true`.

### Disable Table Detection

```bash
pdf2md my-document.pdf --no-tables

```

Outputs raw table cell text without Markdown table syntax—useful when table structure interferes with downstream parsing.

## Programmatic API Configuration

For Rust applications using `pdf-inspector` as a library, construct `MarkdownOptions` directly and pass it through `PdfOptions`.

### Fully Customized Conversion

```rust
use pdf_inspector::{PdfOptions, MarkdownOptions, MarkdownProfile};

let markdown_opts = MarkdownOptions {
    profile: MarkdownProfile::Compact,
    include_page_numbers: true,
    include_images: true,
    include_tables: false,
    preserve_newlines: false,
    base_font_size: 11.0,
    skip_empty_pages: false,
    use_code_fences: true,
    ..MarkdownOptions::default()
};

let pdf_opts = PdfOptions::default().markdown(markdown_opts);
let result = pdf_inspector::process_pdf_with_options("my.pdf", pdf_opts);

println!("{}", result.markdown.unwrap());

```

The `process_pdf_with_options` function in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) accepts this configuration and delegates to the conversion engine in [`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs), which respects each field when generating output.

## Fine-Tuning Heading Detection with base_font_size

The `base_font_size` field (default `12.0`) calibrates how the converter interprets relative font sizes as heading levels.

- **Higher values (14.0+):** Only substantially larger text becomes headings; more content renders as body text
- **Lower values (10.0):** Aggressive heading detection; subtle font changes may trigger `##` or `###` levels

Adjust this when documents use non-standard typography or when heading detection produces too many false positives.

## Source Code Reference Map

Understanding where these options are implemented helps with debugging and extension.

| File | Relevance |
|------|-----------|
| [`src/markdown/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/mod.rs) | `MarkdownOptions` struct definition and `Default` implementation |
| [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) | CLI argument parsing; flag-to-option mapping (lines 540–560) |
| [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) | Public API entry point; `process_pdf_with_options` accepts `PdfOptions` |
| [`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs) | Core conversion logic implementing option behavior |
| [`tests/integration_tests.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/tests/integration_tests.rs) | Test coverage for various `MarkdownOptions` configurations |

## Summary

- **`MarkdownOptions`** in [`src/markdown/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/mod.rs) is the authoritative configuration struct for PDF-to-Markdown conversion
- **Two profiles**—`Standard` and `Compact`—control overall formatting density
- **Eight boolean/numeric fields** govern page numbers, images, tables, newlines, font sizing, empty page handling, and code block style
- **CLI flags** in `pdf2md` provide convenient access without code changes
- **Library API** allows complete programmatic control via `PdfOptions::markdown()`

## Frequently Asked Questions

### How do I minimize token count for LLM processing?

Use `MarkdownProfile::Compact` with `preserve_newlines: false`. This combination removes blank lines, trims whitespace, and collapses consecutive line breaks into single spaces. The `--compact` CLI flag sets the profile; combine with custom code for newline handling if using the library directly.

### Why are my tables rendering as plain text?

Check that `include_tables` is `true` (the default). If explicitly disabled or if table detection fails, raw cell text outputs without pipe (`|`) delimiters. Some PDFs with complex table layouts may also bypass detection—verify with `pdf2md --no-tables` to compare behavior.

### Can I preserve exact page boundaries in output?

Set `skip_empty_pages: false` and `include_page_numbers: true`. This ensures every PDF page appears in the Markdown (including empty ones) with clear `<pagenum>` markers. The CLI equivalent requires the `--page-numbers` flag and custom code or library use to disable empty page skipping.

### Where is base_font_size most useful?

Documents with unusual typography—such as academic papers with small section headers or design portfolios with varied text sizes—benefit from tuning this value. Increase it when normal text is misclassified as headings; decrease it when true headings render as body text.