pdf-to-markdown

name	pdf-to-markdown
description	Use when converting PDF files to markdown for reading, indexing, or processing. Triggers on "convert this PDF", "extract text from PDF", "PDF to markdown", "read this PDF as markdown", "parse PDF", or any task requiring structured text extraction from PDF documents. Uses opendataloader-pdf which requires Java 11+.

PDF to Markdown

Overview

Convert PDF files to clean markdown using opendataloader-pdf — the #1 benchmark PDF parser (0.90 overall accuracy). Runs locally, no cloud dependency. Preserves heading hierarchy, table structure, and reading order.

When to Use

• Converting PDF to markdown for LLM context, RAG pipelines, or indexing
• Extracting structured text (headings, tables, lists) from PDF documents
• Batch-converting a directory of PDFs
• When NOT to use: filling PDF forms, merging/splitting PDFs, visual PDF viewing

Prerequisites

• Java 11+ — run java -version to verify. Install from Adoptium if missing.
• opendataloader-pdf — pip install -U opendataloader-pdf

Core Pattern

Single file

opendataloader-pdf input.pdf --format markdown --output-dir output/

Batch (multiple files or directory)

opendataloader-pdf file1.pdf file2.pdf folder/ --format markdown --output-dir output/

Python API

import opendataloader_pdf

opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="markdown"
)

Each convert() call spawns a JVM process. Batch all files in one call — do not loop.

Output

Markdown files are written to output_dir with the same basename as the input PDF. The output preserves:

• Heading hierarchy (h1–h6)
• Table structure (pipes/dashes)
• List nesting (numbered, bulleted)
• Reading order (XY-Cut++ for multi-column layouts)

Hybrid mode (complex documents)

For scanned PDFs, borderless tables, formulas, or charts — use hybrid mode for higher accuracy (0.49 → 0.93 table accuracy):

pip install -U "opendataloader-pdf[hybrid]"

# Terminal 1: start backend
opendataloader-pdf-hybrid --port 5002

# Terminal 2: process
opendataloader-pdf --hybrid docling-fast file.pdf --format markdown --output-dir output/

Add --force-ocr to the backend for scanned/image-based PDFs. Add --ocr-lang "ko,en" for non-English documents.

Tagged PDF extraction

When a PDF has structure tags, use them for exact layout:

opendataloader_pdf.convert(
    input_path=["tagged.pdf"],
    output_dir="output/",
    format="markdown",
    use_struct_tree=True
)

Decision Matrix

Document type	Mode	Flag
Standard digital PDF	Fast (default)	None
Complex/borderless tables	Hybrid	--hybrid docling-fast
Scanned/image-based PDF	Hybrid + OCR	Backend: --force-ocr
Non-English scanned PDF	Hybrid + OCR + lang	Backend: --force-ocr --ocr-lang
PDF with structure tags	Fast + struct tree	--use-struct-tree

Common Mistakes

Mistake	Fix
Calling convert() in a loop	Batch all files in one convert() call — each spawns JVM
Using hybrid without starting backend	Start opendataloader-pdf-hybrid --port 5002 first
Missing Java	Install JDK 11+ from Adoptium before running
Using --force-ocr on digital PDFs	Only use for scanned/image-based PDFs — slower on digital
Forgetting --hybrid-mode full	Required for formula/picture enrichments on client side