How to Disable Specific Markdown Conversions (Headers, Lists, Code) Using MarkdownOptions in pdf-inspector

Use the detect_headers, detect_lists, and detect_code boolean fields on the MarkdownOptions struct—set any to false to skip that conversion entirely while preserving raw paragraph text.

The pdf-inspector crate parses PDF content and converts structured text into Markdown through a configurable pipeline. This conversion behavior is controlled by MarkdownOptions, defined in src/markdown/mod.rs. When you pass customized options through PdfOptions::markdown(), the conversion engine in src/markdown/convert.rs conditionally applies header detection, list formatting, and code block wrapping based on these flags.

Understanding MarkdownOptions

The MarkdownOptions struct provides granular control over structural detection. Here are the three key fields:

Field	Purpose	Default
detect_headers	Converts font-size heuristics and PDF structure tree headings into Markdown headers (# Heading)	true

| detect_lists | Identifies bullet points and numbered items, formatting them as - item or 1. item | true | | detect_code | Treats indented or monospaced text as fenced code blocks (```) | true |

These fields extend beyond the three shown—MarkdownOptions also includes detect_tables, detect_underline, and check_urls for additional formatting control.

Where the Options Are Applied

The conversion logic lives in src/markdown/convert.rs. Each detection feature is gated by its corresponding option flag. For code blocks, the engine checks detect_code before applying heuristics:

// src/markdown/convert.rs
if options.detect_code && is_code_like(trimmed) {
    if !in_code_block {
        output.push_str("```\n");
        in_code_block = true;
    }
    output.push_str(trimmed);
    output.push('\n');
    continue;
} else if in_code_block {
    output.push_str("```\n");
    in_code_block = false;
}

The same pattern applies to detect_lists and detect_headers elsewhere in the conversion loop. When a flag is false, that structural transformation is bypassed entirely—the text continues through the pipeline as a plain paragraph.

Passing Options Through the API

MarkdownOptions integrates with the public API through PdfOptions. In src/lib.rs, the process_pdf_with_options function accepts a PdfOptions struct, which encapsulates markdown configuration via the .markdown() builder method:

// src/lib.rs — process_pdf_with_options signature
pub fn process_pdf_with_options<P: AsRef<Path>>(
    path: P,
    options: PdfOptions,
) -> Result<ProcessResult>

Because MarkdownOptions implements Default, you only need to specify the fields you want to override.

Practical Code Examples

Disable All Three Conversions

Convert a PDF to plain paragraphs without headers, lists, or code blocks:

use pdf_inspector::{process_pdf_with_options, PdfOptions, MarkdownOptions};

let opts = PdfOptions::new()
    .markdown(MarkdownOptions {
        detect_headers: false,
        detect_lists:   false,
        detect_code:    false,
        ..Default::default()
    });

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

Keep Headers, Remove Lists and Code

Preserve heading structure while outputting list items and code as regular text:

let opts = PdfOptions::new()
    .markdown(MarkdownOptions {
        detect_lists: false,
        detect_code:  false,
        ..Default::default()  // detect_headers remains true
    });

let md = process_pdf_with_options("technical_spec.pdf", opts)?.markdown;

Selective Single-Feature Disable

Only suppress code block detection while keeping headers and lists:

let opts = PdfOptions::new()
    .markdown(MarkdownOptions {
        detect_code: false,
        ..Default::default()
    });

CLI Binary Support

The command-line interface in src/bin/pdf2md.rs exposes these same options as flags. While flag names may vary by version, the underlying mechanism translates CLI arguments into MarkdownOptions fields before calling process_pdf_with_options.

Example invocation pattern:

# Default behavior—all conversions enabled

./pdf2md input.pdf

# Disable specific conversions

./pdf2md input.pdf --no-headers --no-lists

Consult the binary source for exact flag names in your installed version.

Key Source Files

File	Relevance
src/markdown/mod.rs	MarkdownOptions struct definition with Default implementation
src/markdown/convert.rs	Conversion loop applying option-gated detection heuristics
src/lib.rs	Public API entry point process_pdf_with_options
src/bin/pdf2md.rs	CLI wrapper demonstrating options usage

Summary

• Three boolean flags control Markdown structural detection: detect_headers, detect_lists, and detect_code
• Set any flag to false to skip that conversion—raw text passes through unchanged
• MarkdownOptions uses struct update syntax with ..Default::default() for concise partial overrides
• Options flow through PdfOptions::markdown() to the core conversion engine
• The CLI binary provides command-line access to the same configuration

Frequently Asked Questions

What happens to text when detect_headers is disabled?

The text that would have become a Markdown header (# Title) is emitted as a plain paragraph instead. The font size and structural information from the PDF structure tree is ignored during conversion, though the raw text content is preserved.

Can I disable these conversions without recompiling?

Yes—if you use the provided CLI binary. The pdf2md utility accepts flags that map directly to MarkdownOptions fields. For programmatic use, construct MarkdownOptions with the desired flags and pass it to process_pdf_with_options.

Are there performance benefits to disabling detections?

Minimal. The heuristics run regardless of the flag state, but the conversion step is skipped when a flag is false. The primary benefit is output control rather than speed—disabling detections produces cleaner plain-text output for PDFs where structural heuristics produce false positives.

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