PDF to Markdown with Pandoc: A Working Route
Extract or OCR the PDF first, then use Pandoc only when you need to turn the recovered structure into Markdown. Converting a PDF to Markdown with Pandoc has four useful starting points: an original structured document, readable PDF text, content whose meaning depends on layout, and scanned or mixed pages. Pandoc's built-in readers cannot import the PDF itself. 13
Choose the source before choosing the command
The source you have determines which stage needs work. An original document with heading styles and table cells gives a converter explicit structure. A PDF-only workflow must recover that structure from the page, and a scanned page first needs text recognition.
| What you have | Observable test | Route |
|---|---|---|
| Original DOCX or semantic HTML | The source contains heading styles or heading tags, and actual table cells | Send that source to Pandoc |
| Selectable prose in a simple PDF | Copy a paragraph into an editor and read it from beginning to end without missing or interleaved words | Extract text or Markdown first, with paragraph cleanup where needed |
| Tables, stacked headers, columns, or displayed expressions | Copy a row, column, or expression: labels separate from values, sentences interleave, or notation changes | Use an extractor that reconstructs layout, then inspect the affected structure |
| A scan or a mixed document | A visibly printed passage produces no text when copied, even though other pages copy correctly | Use OCR for the affected pages before Markdown serialization |
Apply the copying test to the pages you need, including pages with different layouts. A readable introduction does not tell you whether an invoice table or an appended scan survived. 1214
Pandoc writes the structure its input contains
Pandoc can preserve document structure only after a supported reader receives it. Its reader parses the input into a document tree, and its writer serializes that tree. Selecting a PDF engine changes PDF output, while selecting an input format chooses the parser. 2
The diagnostic command pandoc --list-input-formats lists the built-in readers. A direct command such as pandoc input.pdf -t gfm -o output.md is an unsupported-input probe: it stops before content conversion. Changing the filename to HTML would label the same PDF bytes as a different format without extracting anything. 1313
An original DOCX can go straight through Pandoc because it already contains document elements:
pandoc input.docx -f docx -t gfm --wrap=none -o output.md
Output from our structured-document sample, unedited:
# Quarterly Migration Report
The migration moved fourteen services from the legacy cluster to the new platform. Each service kept its public endpoint during the move.
## Scope and Schedule
This control document retained its headings, list items, and table rows. It is an independent DOCX fixture, not the original of a tested PDF. Recovering a DOCX from a PDF adds an earlier reconstruction step whose accuracy this control does not measure. 1214
For a PDF that only needs readable text, PyMuPDF can produce an HTML intermediate. This example excludes images and performs no OCR:
from pathlib import Path
import pymupdf
flags = pymupdf.TEXTFLAGS_HTML & ~pymupdf.TEXT_PRESERVE_IMAGES
with pymupdf.open("input.pdf") as document:
html = "\n".join(page.get_text("html", flags=flags) for page in document)
Path("input.html").write_text(html, encoding="utf-8")
pandoc input.html -f html -t gfm-raw_html --wrap=none -o output.md
Disabling raw HTML removes the style wrappers from this output. It does not infer the table hidden among positioned text fragments. Our invoice became separate paragraphs, with labels detached from their values. Visual line endings also remained paragraph boundaries in the prose fixture. 1213
Output from our invoice sample, unedited:
**Quarterly invoice summary**
**Item**
**Qty**
**Unit Price**
Pandoc's HTML parser sends paragraph tags to its paragraph parser, heading tags to its heading parser, and table tags to its table parser. A larger font inside a paragraph does not enter the heading branch. For this intermediate, the missing table structure belongs to the extraction stage. 4
The command pandoc input.html -f html -t native exposes that parsed structure. A recovered invoice represented by paragraph nodes without a table node needs reconstruction upstream. A table node with a damaged output points you toward the writer or target syntax instead. 413
| Failure condition | What the output shows | Action |
|---|---|---|
| PDF passed directly to Pandoc | Input is rejected | Extract into a supported format first |
| Positioned text exported as HTML | Labels and values occupy separate paragraphs | Reconstruct the table before serialization |
| Scanned page exported without OCR | The visible passage is absent | Add recognition before the HTML or Markdown stage |
MarkItDown needs separate checks for rows and reading order
MarkItDown can keep simple table rows while still scrambling a column-based page. Its PDF converter includes a word-position heuristic for form-like content, with a text-extraction fallback. 56
from pathlib import Path
from markitdown import MarkItDown
result = MarkItDown(enable_plugins=False).convert_local("input.pdf")
Path("output.md").write_text(result.markdown, encoding="utf-8")
The invoice's body rows stayed together on the sample PDF used for this guide. The stacked price header split across output lines, so the relationship between the price group and its leaf labels needed attention. The column sample had a different failure: pieces of the right-hand column interrupted sentences from the left. 1214
Output from our column sample, unedited:
Invoice reconciliation starts with the export file, not
Demand forecasts fail upward more often than they
the ledger. Teams that reconcile weekly pull the
fail downward. Optimistic sales inputs push safety
The jump from invoice reconciliation to demand forecasts occurs inside an unfinished sentence. That is a reading-order failure, even though the output contains words from both columns. Running the resulting Markdown through Pandoc gives its reader the already interleaved sequence. A writer option cannot determine which column those fragments originally belonged to. 614
| Failure condition | Visible symptom | Consequence |
|---|---|---|
| Stacked or rotated table labels | Body rows look plausible but the header no longer maps cleanly to them | Repair the header independently of the row data |
| Multiple text columns | A sentence switches topic before it ends | Change the extraction path before formatting Markdown |
| Scan with plugins disabled | No recognized passage appears | Supply an OCR step |
For readable prose or a simple invoice, this path may already produce the Markdown you need.
PyMuPDF4LLM handles layout with an OCR dependency
PyMuPDF4LLM can preserve column order, while scanned text still requires an available OCR engine. Its layout analysis and its recognition engine perform separate jobs. Our environment had the layout package enabled and no usable OCR function. 715
from pathlib import Path
import pymupdf4llm
markdown = pymupdf4llm.to_markdown("input.pdf")
Path("output.md").write_text(markdown, encoding="utf-8")
The column fixture read down the left column before moving to the right. The invoice retained its body rows, but the stacked header still occupied separate lines. 1214
Output from our stacked-header sample, unedited:
|**Item**|**Qty**|**Price**||
|---|---|---|---|
|||**Unit**|**Total**|
|Consulting hours|12|85.00|1020.00|
|Data export fee|3|40.00|120.00|
|Template license|1|190.00|190.00|
The mixed fixture's prose and invoice survived, while its scanned passage was absent. Enabling an OCR option cannot supply a missing recognition engine. For a mixed document, compare a phrase from each visually distinct page against the result: a nonempty Markdown file can still omit the scan. 71215
Markovo's archived PDF to Markdown workflow result recovered the scanned passage in that mixed fixture. Its expression output also contained nested display delimiters. 121617
Output from our displayed-expression sample, unedited:
$$
\[\mathsf{E}=\mathsf{m}\mathsf{c}\mathsf{^2}\]
$$
| Failure condition | Visible symptom | Action |
|---|---|---|
| No usable OCR engine | Text pages convert while scanned passages disappear | Configure recognition or use an OCR-capable extraction path |
| Stacked or rotated headers | Labels split or lose their association with columns | Compare the header with the page, separately from body rows |
| Expression formatting changes | Extra delimiters or altered notation appear | Inspect the expression and the target renderer's accepted math syntax |
Fix the stage that first loses meaning
Repair the first stage whose output loses the required meaning. An input rejection, a missing table relationship, and an absent scanned passage point to different work:
| Symptom | Responsible stage to investigate | Concrete next step |
|---|---|---|
| Pandoc refuses the PDF | Input selection | Use a supported original source or a PDF extractor |
| HTML opens but the table becomes paragraphs | Structure recovery | Inspect the parsed document tree, then rebuild or re-extract the table |
| Markdown mixes unrelated sentence fragments | Reading-order recovery | Use a layout path and compare the column transition |
| Text pages survive but a scan is absent | Recognition | Add a usable OCR engine for the affected page |
| Rows survive but the grouped header is ambiguous | Table interpretation | Resolve the group-to-column mapping before using the values |
For an original structured source, Pandoc is the direct route to Markdown. For a PDF-only source, text extraction serves readable prose, layout recovery serves relationships across the page, and OCR supplies text that is present only as pixels. A dedicated Markdown extractor may finish the job without Pandoc. Use Pandoc after recovery when the supported input contains the structure your target needs.
How we tested
The tests isolate PDF input, intermediate structure, layout recovery, and OCR availability on synthetic fixtures.
Markovo is the service we build. It ran through the same corpus and scorer as the other paths; its row is reported in full, including where it scored lower.
Corpus and execution scope
Local conversions and scoring ran on 2026-11-06 with Python 3.11.14. The PDFs and matching truth files were supplied in this run. Their labels describe the property being tested:
File under lab/corpus/ |
Shape and test boundary |
|---|---|
prose-single.pdf |
Single-column prose |
table-simple.pdf |
Simple ruled invoice |
table-merged-header.pdf |
Stacked group and leaf labels, with a visible divider in the upper row |
two-column.pdf |
Paragraphs down the left column, then down the right |
scan-image.pdf |
A printed passage embedded as an image without a text layer |
mixed.pdf |
Prose, invoice, then image-only scan |
equation.pdf |
Short linear expressions, not a test of complex typeset mathematics |
rotated-header.pdf |
Rotated header text above ordinary body rows |
report.docx |
Independent structured-source control, not the original of any tested PDF |
report.docx is mentioned as an input and is excluded from the publishable evidence bundle. Its output and truth are publishable. Each PDF has a matching <sample>.truth.json. The tests do not cover encrypted documents, handwriting, production-scale document collections, or rendered GitHub pages.
| Path | Version and options |
|---|---|
| MarkItDown | 0.1.8, plugins disabled, convert_local |
| PyMuPDF4LLM | 1.28.2 with PyMuPDF/layout 1.28.2, default to_markdown, no usable OCR function |
| PyMuPDF HTML → Pandoc | PyMuPDF 1.28.2 text-only HTML, images excluded, no OCR. Pandoc 3.11, -f html -t gfm-raw_html --wrap=none |
| Pandoc structured-source control | 3.11, -f docx -t gfm --wrap=none |
| Markovo | Archived API outputs, jobs created 2026-10-06, handed over and rescored 2026-11-06. The recorded rate-card identifier is a billing contract identifier, not a converter build version |
The archived Markovo source names and byte counts match the supplied PDFs. The API snapshots contain no source hashes, so byte identity relies on the runner's same-corpus handoff rather than an independently verified API hash. No new Markovo request was sent in this session. The stored API sequence is POST /v1/convert, polling GET /v1/jobs/{job_id} to succeeded, then GET /v1/jobs/{job_id}/download. 16
The mixed response reports pages_total=3 and pages_ocr=3, while its final billing_metrics.pagesOcr=1. The request snapshot has billing_metrics.ocrPageIndexes=[2]. Those fields support an OCR target in the request, but their disagreement prevents a precise claim about final per-page routing. The preserved output contains the scanned text. Other archived single-page counters also disagree. 1316
Commands and raw evidence
Run from the repository root with the dependencies already installed. Output logging redirections are omitted:
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python tools/lab_run.py \
--lab runs/2026-11-06-markovo-pdf-to-markdown-pandoc/lab \
--tools markitdown,pymupdf4llm \
--samples prose-single,table-simple,table-merged-header,two-column,scan-image,mixed,equation,rotated-header,report \
--heavy-cache '' --markovo-cache ''
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python \
runs/2026-11-06-markovo-pdf-to-markdown-pandoc/lab/run_probe.py
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python tools/lab_score.py \
--lab runs/2026-11-06-markovo-pdf-to-markdown-pandoc/lab \
--out runs/2026-11-06-markovo-pdf-to-markdown-pandoc/lab/scores.json \
--markdown runs/2026-11-06-markovo-pdf-to-markdown-pandoc/lab/scores.md
The probe also ran direct PDF input on every PDF, and an explicit -f pdf probe. All were rejected with exit code 21. These are unsupported-input results, not extraction-quality measurements. The DOCX control retained all tested headings, heading levels, list items, prose, and table rows. 1213
Raw files are lab/markitdown/<sample>.md, lab/pymupdf4llm/<sample>.md, lab/pymupdf-html-pandoc-clean/<sample>.md, and lab/markovo/<sample>.md. The control is lab/pandoc/report.md. The HTML intermediates are saved verbatim as lab/pymupdf-html-pandoc/<sample>.input.txt, with parsed trees in lab/pandoc-ast/<sample>.json. The probe, scorer, local converter sources, commands, environment, and first twenty lines of each output are included in the evidence files. 1314
An exploratory default -t gfm pass retained HTML wrappers and is also recorded in lab/scores.json. Those wrappers interrupt literal sentence matches without proving text was deleted. The table below uses the clean writer variant. The MarkItDown OCR plugin was not executed for this guide. Reports of missing tables, scan output containing only page labels, and formula conversion problems were read as historical reports, without reproducing the reporters' original attachments. 8910
Scoring definitions and results
tools/lab_score.py computes the following checks. These are string and structure proxies, with no aggregate quality score. 12
| Column | Definition |
|---|---|
| Prose | Fraction of reference sentences with at least four normalized words found in the output |
| Order | Fraction of adjacent paragraph-anchor pairs in increasing order, using the first six words. Missing anchors fail the pair |
| Rows | Fraction of reference rows whose cell strings all occur on one output line |
| Header | All leaf-header strings occur on one line. This does not validate group spans or cell placement |
| Pipe | A pipe-delimited header and separator were detected. no does not reject an HTML table |
| Pages | Fraction of mixed-document page anchors found, not a physical page count |
| Scan | Reference scanned-sentence matches using the Prose rule |
| Expr | Reference expression matches after math-markup normalization, not proof of mathematical equivalence or renderer validity |
| Seconds | Recorded elapsed time, with the timing limits below |
A single-line HTML table can satisfy Rows or Header despite a cell-assignment error. Paragraph anchors can occur in order while sentence fragments are interleaved. These limitations are why the prose shows actual output and why the header condition remains separate from row retention. 12
Local times come from one pass. The clean HTML route measures its Pandoc subprocess after reusing the HTML input. MarkItDown and PyMuPDF4LLM measure their conversion calls. The cached Markovo records contain 0.0 placeholders, shown as n/a below. These timing scopes support no speed ranking. n/a in other columns means the check does not apply.
| Tool | Sample | Prose | Order | Rows | Header | Pipe | Pages | Scan | Expr | Seconds |
|---|---|---|---|---|---|---|---|---|---|---|
| markitdown | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | 0.0213 |
| markitdown | table-simple | n/a | n/a | 1.0 | 1.0 | yes | n/a | n/a | n/a | 0.011 |
| markitdown | table-merged-header | n/a | n/a | 1.0 | 0.0 | yes | n/a | n/a | n/a | 0.0112 |
| markitdown | two-column | 0.1111 | 0.8 | n/a | n/a | n/a | n/a | n/a | n/a | 0.0351 |
| markitdown | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 0.0 | n/a | 0.0073 |
| markitdown | mixed | 1.0 | n/a | 1.0 | 1.0 | yes | 0.6667 | 0.0 | n/a | 0.0261 |
| markitdown | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 1.0 | 0.0574 |
| markitdown | rotated-header | n/a | n/a | 1.0 | 0.0 | yes | n/a | n/a | n/a | 0.0107 |
| pymupdf4llm | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | 0.1631 |
| pymupdf4llm | table-simple | n/a | n/a | 1.0 | 1.0 | yes | n/a | n/a | n/a | 0.1543 |
| pymupdf4llm | table-merged-header | n/a | n/a | 1.0 | 0.0 | yes | n/a | n/a | n/a | 0.1513 |
| pymupdf4llm | two-column | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | 0.1485 |
| pymupdf4llm | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 0.0 | n/a | 0.1851 |
| pymupdf4llm | mixed | 1.0 | n/a | 1.0 | 1.0 | yes | 0.6667 | 0.0 | n/a | 0.4019 |
| pymupdf4llm | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.75 | 0.2188 |
| pymupdf4llm | rotated-header | n/a | n/a | 1.0 | 0.0 | yes | n/a | n/a | n/a | 0.1558 |
| pymupdf-html-pandoc-clean | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | 0.0267 |
| pymupdf-html-pandoc-clean | table-simple | n/a | n/a | 0.0 | 0.0 | no | n/a | n/a | n/a | 0.027 |
| pymupdf-html-pandoc-clean | table-merged-header | n/a | n/a | 0.0 | 0.0 | no | n/a | n/a | n/a | 0.0476 |
| pymupdf-html-pandoc-clean | two-column | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | 0.0442 |
| pymupdf-html-pandoc-clean | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 0.0 | n/a | 0.0331 |
| pymupdf-html-pandoc-clean | mixed | 1.0 | n/a | 0.0 | 0.0 | no | 0.6667 | 0.0 | n/a | 0.0266 |
| pymupdf-html-pandoc-clean | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 1.0 | 0.0258 |
| pymupdf-html-pandoc-clean | rotated-header | n/a | n/a | 0.0 | 0.0 | no | n/a | n/a | n/a | 0.0286 |
| markovo | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a (cached) |
| markovo | table-simple | n/a | n/a | 1.0 | 1.0 | no | n/a | n/a | n/a | n/a (cached) |
| markovo | table-merged-header | n/a | n/a | 1.0 | 1.0 | no | n/a | n/a | n/a | n/a (cached) |
| markovo | two-column | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a (cached) |
| markovo | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 1.0 | n/a | n/a (cached) |
| markovo | mixed | 1.0 | n/a | 1.0 | 1.0 | no | 1.0 | 1.0 | n/a | n/a (cached) |
| markovo | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.5 | n/a (cached) |
| markovo | rotated-header | n/a | n/a | 1.0 | 1.0 | no | n/a | n/a | n/a | n/a (cached) |
The Markovo expression row is lower than the local text paths. The fixture uses linear strings, and the normalizer does not establish mathematical equivalence. Its successful text recovery and its expression-formatting problems are separate observations. 1217
Sources
- Pandoc FAQ: PDF input
- Pandoc User Guide: readers, writers and extensions
- Pandoc 3.11 reader registry
- Pandoc 3.11 HTML parser
- MarkItDown 0.1.8 README
- MarkItDown 0.1.8 PDF converter source
- PyMuPDF4LLM 1.28.2 README
- Historical report: PDF tables
- Historical report: OCR plugin scan output
- Historical report: formula conversion
- Synthetic-corpus scorer output
- Pandoc input, AST and archive-provenance probes
- Commands and unedited output excerpts
- Local layout and OCR availability
- Archived Markovo mixed-document API response
- Archived Markovo expression output


