PdfConverter

Convert PDF files to Markdown with intelligent table extraction

Overview

The PdfConverter class converts PDF documents to Markdown, with advanced features for extracting tables into properly formatted Markdown tables. It uses a hybrid approach combining pdfplumber for form-style documents and pdfminer for text-heavy documents.

Dependencies

pip

pip install markitdown[pdf]

Requires: pdfminer.six, pdfplumber

Accepted Formats

MIME Types · list

• application/pdf
• application/x-pdf

Extensions · list

• .pdf

Methods

accepts()

def accepts(
    file_stream: BinaryIO,
    stream_info: StreamInfo,
    **kwargs: Any,
) -> bool

Returns True if the file has a .pdf extension or PDF MIME type.

convert()

def convert(
    file_stream: BinaryIO,
    stream_info: StreamInfo,
    **kwargs: Any,
) -> DocumentConverterResult

Converts a PDF file to Markdown.

Returns: DocumentConverterResult with converted Markdown text

Raises: MissingDependencyException if PDF dependencies are not installed

Features

Intelligent Extraction Strategy

The converter analyzes each page and selects the optimal extraction method:

1. Form-Style Extraction - For documents with structured layouts (forms, invoices, tables)

   • Analyzes word positions to detect column structures
   • Extracts borderless tables by detecting aligned text
   • Generates properly formatted Markdown tables with headers and separators

2. Text Extraction - For plain text documents (reports, articles)

   • Falls back to pdfminer for better text spacing and readability
   • Used when less than 20% of pages are form-style

Table Detection

The converter detects tables by:

• Analyzing word positions and alignment across rows
• Identifying consistent column structures (3-20 columns)
• Detecting header rows and data rows
• Filtering out multi-column text layouts (scientific papers)

Special Formatting

MasterFormat Numbering - Automatically merges partial numbering patterns:

.1
The intent of this Request for Proposal...

Becomes:

.1 The intent of this Request for Proposal...

Example Usage

from markitdown.converters import PdfConverter
from markitdown._stream_info import StreamInfo

converter = PdfConverter()

with open("document.pdf", "rb") as f:
    stream_info = StreamInfo(extension=".pdf")
    
    if converter.accepts(f, stream_info):
        result = converter.convert(f, stream_info)
        print(result.markdown)

Output Example

For a PDF with tables:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

Regular paragraph text appears as plain markdown.

| Header A | Header B |
| -------- | -------- |
| Data A   | Data B   |

Implementation Details

Source Location

~/workspace/source/packages/markitdown/src/markitdown/converters/_pdf_converter.py:495

Key Functions

• _extract_form_content_from_words() - Detects and extracts form-style tables
• _extract_tables_from_words() - Extracts traditional bordered tables
• _merge_partial_numbering_lines() - Post-processes MasterFormat numbering
• _to_markdown_table() - Formats extracted tables as Markdown

Algorithm Highlights

1. Adaptive Tolerance - Column boundaries calculated using 70th percentile of gaps
2. Column Clustering - Groups nearby x-positions into columns (configurable tolerance)
3. Table Quality Validation - Ensures detected tables have consistent structure
4. Hybrid Fallback - Automatically switches extraction method if needed

Performance Considerations

• PDF is read into memory (BytesIO) for compatibility with both libraries
• Pages are processed sequentially
• Large PDFs may require significant memory
• Complex forms with 15+ columns use adaptive extraction