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

  1. Pandoc FAQ: PDF input
  2. Pandoc User Guide: readers, writers and extensions
  3. Pandoc 3.11 reader registry
  4. Pandoc 3.11 HTML parser
  5. MarkItDown 0.1.8 README
  6. MarkItDown 0.1.8 PDF converter source
  7. PyMuPDF4LLM 1.28.2 README
  8. Historical report: PDF tables
  9. Historical report: OCR plugin scan output
  10. Historical report: formula conversion
  11. Synthetic-corpus scorer output
  12. Pandoc input, AST and archive-provenance probes
  13. Commands and unedited output excerpts
  14. Local layout and OCR availability
  15. Archived Markovo mixed-document API response
  16. Archived Markovo expression output