What Is MarkPDFDown? Converting PDF Pages to Markdown with a Vision LLM¶

For / Key Points

For: Developers converting PDFs with tables, formulas, or complex layouts into Markdown for RAG, search, or summarization.

Key Points:

MarkPDFDown renders each page as an image and asks a multimodal LLM to transcribe it
Visual conversion can preserve difficult layouts, but API transfer, latency, and usage grow with page count
Check confidentiality first, then reconcile pages, tables, formulas, and reading order against the source

MarkPDFDown does not simply extract the embedded text layer from a PDF. It renders the PDF at 300 dpi, then sends each page image to a multimodal LLM for Markdown transcription.¹² That approach can recover tables, formulas, and multi-column layouts visually, but it also sends document content to the configured LLM provider.

This article answers one question: Which PDFs suit MarkPDFDown, and how should you validate the output before using it as LLM input?

Use it first on a small set of visually difficult PDFs¶

MarkPDFDown is most relevant when ordinary text extraction breaks reading order or structure. Candidates include two-column papers, irregular tables, mathematical notation, and scanned documents stored as images.

A large collection with a clean text layer should not automatically start here. Local extraction avoids image transfer and page-by-page inference when the structure is already usable.

PDF condition	First option	Role for MarkPDFDown
Selectable text and simple layout	Local text extraction	Compare only if reading order breaks
Scanned image with mostly prose	OCR	Try it when tables or formulas lose structure
Many tables, formulas, diagrams, or columns	Vision-based conversion	Strong candidate
Confidential content	Approved closed processing path	Do not use the default external API path

Open source does not imply local-only processing. MarkPDFDown is Apache-2.0 licensed, while its conversion path uses LiteLLM to send page images to OpenAI or OpenRouter.¹³

The pipeline transcribes one page image at a time¶

The processing flow is simple enough to reason about. It does not send the complete PDF to one model call.

PDF
  ↓ render at 300 dpi with PyMuPDF
page_0001.jpg, page_0002.jpg, ...
  ↓ send one page at a time through LiteLLM
Markdown for each page
  ↓ join with blank lines
output.md

The transcription prompt asks the model to identify headings, text styles, formulas, and table rows and columns, with formulas represented in LaTeX.⁴ The tool also accepts JPG, JPEG, PNG, BMP, and GIF inputs.¹

The current implementation processes pages sequentially. Operationally, latency and API usage should therefore be expected to grow approximately with page count. This is an inference from the implementation, not a pricing guarantee.⁴

Install the repository and run it with uv¶

The official README recommends cloning the repository and using uv to install its dependencies.¹ You need Python 3.9 or later and an API key for the selected LLM provider.

git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown
uv sync
uv pip install -e .
cp .env.sample .env

Configure the model and API key in .env. The following mirrors the repository's basic OpenAI example; verify current model availability and pricing before running it.

MODEL_NAME=gpt-4o
OPENAI_API_KEY=your-openai-api-key
TEMPERATURE=0.3
MAX_TOKENS=8192
RETRY_TIMES=3

Run a basic file conversion with:

markpdfdown --input document.pdf --output document.md

For a large document, start with five pages. Page numbers are one-based, and --end 0 means the last page.⁵

markpdfdown \
  --input document.pdf \
  --output sample.md \
  --start 1 \
  --end 5

Docker and stdin/stdout modes are also available, but file mode makes an initial evaluation easier to diagnose. A separate desktop project can be started with npx -y markpdfdown.⁶

Reconcile four things against the source PDF¶

A generated Markdown file does not prove that every page converted successfully. In the current implementation, a failed LLM call for one page is logged and returns an empty string; only non-empty page results are joined.⁴ The command can therefore produce an output even when intermediate content is missing.

At minimum, inspect four dimensions:

Page coverage: every source page has corresponding content
Tables: row and column counts, merged cells, units, and notes survived
Formulas: symbols, subscripts, fractions, and equation numbers match
Reading order: columns, footnotes, and captions appear in the right sequence

For RAG ingestion, add page-boundary comments or metadata in a post-processing step. The current output joins page results with blank lines, so strict source-page traceability must be designed by the caller.⁴

Test five pages to discover failure modes, not to claim a single accuracy score.

MarkPDFDown and Microsoft MarkItDown are separate projects¶

MarkPDFDown is not Microsoft's MarkItDown. MarkPDFDown concentrates on vision-model transcription of PDFs and images.

Microsoft MarkItDown converts a wider set of formats, including PowerPoint, Word, Excel, PDF, images, audio, and HTML, through format-specific converters.⁷ The similar names make it easy to copy commands from the wrong repository.

	MarkPDFDown	Microsoft MarkItDown
Main inputs	PDF and images	Office, PDF, images, audio, and more
Core design	Vision-LLM page transcription	Format-specific conversion to Markdown
External LLM	Central to conversion	Optional for selected features
Choose it when	Visual structure matters	Many file types need one entry point

Star counts do not decide between them. The decision turns on whether visual interpretation or broad format coverage matters more.

Summary: Separate conversion from acceptance in production¶

Generating Markdown and accepting that Markdown into search or RAG should be separate stages. Automatic indexing can turn an omitted page or mistranscribed formula into durable system knowledge.

Keep a manifest with the source hash, page count, model, conversion timestamp, and review result. That record makes model changes and re-conversion easier to compare.

MarkPDFDown is an entry point for making difficult PDFs machine-readable. Turning the result into trusted knowledge still requires page-level reconciliation and a separate acceptance decision.

RAG / Context Engineering — Design retrieval and evaluation after conversion
What Is LiteLLM? — Understand the model-routing layer used by MarkPDFDown
Why Office files are fragile AI inputs — Prevent structure loss in document pipelines
Claude Document Skills — Validate Office artifacts on the generation side