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

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 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 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 maps command-line flags to these fields.

Core Configuration Fields

Each field directly influences how the conversion engine in 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 exposes these options through intuitive flags.

Basic Conversion with Defaults

pdf2md my-document.pdf

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

Compact Output with Page Numbers

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

Maps directly to:

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

This configuration (lines 544–546 in src/bin/pdf2md.rs) is ideal when feeding PDF content into AI systems with limited context windows.

Include Extracted Images

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

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

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 accepts this configuration and delegates to the conversion engine in 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	MarkdownOptions struct definition and Default implementation
src/bin/pdf2md.rs	CLI argument parsing; flag-to-option mapping (lines 540–560)
src/lib.rs	Public API entry point; process_pdf_with_options accepts PdfOptions
src/markdown/convert.rs	Core conversion logic implementing option behavior
tests/integration_tests.rs	Test coverage for various MarkdownOptions configurations

Summary

• MarkdownOptions in 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.

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