Convert PDF to text: match the extraction path
Use native extraction for selectable prose, preserve layout when columns or tables carry meaning, and use OCR for image text. To convert a PDF to text, distinguish five cases: prose, columns, tables, image or mixed pages, and equations. MarkItDown and PyMuPDF4LLM cover the local paths tested here. Archived Markovo API outputs show an OCR path, including a case where expressions changed. 111
Match PDF text conversion to page structure
Choose the extraction path from what the page contains and what its words must remain attached to.
| Page feature | How to identify it | Path to use |
|---|---|---|
| Selectable prose | Copy a sentence into an editor. The words and their order match the source | Native extraction, with paragraph boundaries retained |
| Multiple columns | Copy across a column boundary. Unrelated sentences become neighbors | Layout reconstruction that keeps the columns separate |
| Tables | Follow a value to its header, including any label spanning columns | Retain table structure and map grouped headers to the destination fields |
| Image text or mixed pages | Copy the visible passage into an editor. Its words are absent even if other pages export text | OCR for the unread image text, then combine it with the extracted content |
| Equations | Compare the exported expression with the source, including exponents and subscripts | Retain the original expression as the reference. Accept an extraction only if its notation survives |
PDF to text conversion produces a new representation. It does not edit the original PDF in place. Markdown can retain headings and table boundaries in that text. Renaming a Markdown file to TXT leaves its markup in the file. 1
A nonempty export can still omit a scanned page. In the mixed sample, the native prose and table produced output while the image-only page supplied no recognized words. Classify the distinct page shapes separately instead of treating the document as uniformly native text. 11
MarkItDown changes extraction with document composition
MarkItDown can read a column page differently after a table page is added to the same document.
For prose that copies in its intended order, this local example writes Markdown with optional plugins disabled. Any table markup produced by the converter stays in the output. The snippet ran against the sample PDF used for this guide. 112
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")
On our sample with columns separated by a wide gap, MarkItDown kept the prose readable when the page was converted alone. After we appended a table, the unchanged column page mixed invoice reconciliation with demand forecasting. The document's composition changed the result on a page whose words and geometry had not changed. 1116
The installed converter collects page results and counts pages classified as forms. When it finds none, it discards those chunks and extracts the whole document through a different text engine. When it finds a form page, it keeps the collected page results. The appended table changed that branch in our controlled pair. 23
Output from our column sample with an appended table, unedited:
Invoice reconciliation starts with the export file, not
the ledger. Teams that reconcile weekly pull the Demand forecasts fail upward more often than
payment provider's settlement report first, match it they fail downward. Optimistic sales inputs push
against issued invoices by number, and only then safety stock up for slow movers, and the excess
open the accounting system. Skipping the export sits in the warehouse for two quarters before
step leaves ghost receivables that nobody can anyone reopens the spreadsheet. A weekly report
The original sample with a narrower gap already interleaved prose before we appended a table. That variant changed line grouping without demonstrating a new readability regression. 11
| Failure condition | Visible result | Response |
|---|---|---|
| Columns pass through a path that groups text across the page | A sentence about invoices runs into an unrelated forecast sentence | Keep separate column blocks through a layout path |
| A page contains only an image of words | No recognized words appear for that page | Use an OCR path |
| A header spans columns or contains rotated text | Header labels split or reorder even though data rows remain | Map the header hierarchy before treating rows as records |
Converting pages separately would keep a form page from selecting the branch for another page. It would not repair the original column fixture, which already failed alone. 211
PyMuPDF4LLM retains columns but splits some headers
PyMuPDF4LLM kept the tested column paragraphs in order, but its reconstructed table headers still needed repair.
This example requests page chunks with OCR disabled. It tests layout recovery from existing characters. Its empty scan output belongs to that configuration. It is not a test of the library's available OCR configurations. The code uses the installed wrapper whose source accompanies the results. 512
from pathlib import Path
import pymupdf4llm
chunks = pymupdf4llm.to_markdown("input.pdf", page_chunks=True, use_ocr=False)
Path("output.md").write_text(
"\n\n".join(chunk["text"] for chunk in chunks), encoding="utf-8"
)
Both the original column sample and the wider control retained their paragraph sequence through this path. The grouped-header table exposed another limit: the data rows survived, while the parent label sat above the subordinate labels in a separate Markdown row. An importer that accepts a flat header needs those levels mapped to its destination columns. 11
Output from our grouped-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 source places a price label over the unit and total columns. A consumer that accepts only the first Markdown row as its header receives empty labels for part of that relationship. 11
| Failure condition | Visible result | Response |
|---|---|---|
| The table has grouped headers | Parent and leaf labels occupy separate rows | Keep the hierarchy or flatten it with explicit combined labels |
| The source rotates a header | The price label splits between header rows | Reconstruct the label from its source column |
| OCR is disabled on image text | The scanned passage has no recognized words | Resolve it through an OCR configuration before accepting the document |
| An expression needs exact notation | A source expression is absent from the text | Keep the source expression available for correction |
For this invoice, combined labels such as "Unit price" and "Total price" express the grouping in a flat schema. 11
Markovo recovers scans with limits on expressions
The archived Markovo run recovered the scanned passage in our mixed PDF, while its equation output altered some expressions.
Markovo's PDF to Markdown converter returns a structured text intermediate. The product capability snapshot lists PDF as Available. The results discussed here are archived API downloads, not conversions submitted during this writing session. 910
With an authenticated key and an explicit request bound in the environment, the standard-library client submits to POST /v1/convert, polls GET /v1/jobs/{job_id} until succeeded, then downloads Markdown from GET /v1/jobs/{job_id}/download. The client was exercised through offline archive replay. The content results come from the upstream API runs. 1217
from pathlib import Path
from urllib.request import Request, urlopen
import json
import os
import time
import uuid
base = "https://markovo.net"
auth = {"Authorization": "Bearer " + os.environ["MARKOVO_API_KEY"]}
boundary = uuid.uuid4().hex
fields = {"capability_id": "pdf-to-markdown", "mode": "fast",
"max_credit_units": os.environ["MARKOVO_MAX_CREDIT_UNITS"]}
parts = [
(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"'
f'\r\n\r\n{value}\r\n').encode()
for name, value in fields.items()
]
parts.append(
(f'--{boundary}\r\nContent-Disposition: form-data; name="file"; '
'filename="input.pdf"\r\nContent-Type: application/pdf\r\n\r\n').encode()
+ Path("input.pdf").read_bytes() + b"\r\n"
)
parts.append(f"--{boundary}--\r\n".encode())
def read_json(request):
with urlopen(request, timeout=60) as response:
return json.load(response)
# Submit once, then poll the returned job.
submitted = read_json(Request(
base + "/v1/convert", data=b"".join(parts), method="POST",
headers={**auth, "Content-Type": "multipart/form-data; boundary=" + boundary}
))
job_id = submitted["job_id"]
for _ in range(120):
payload = read_json(Request(base + "/v1/jobs/" + job_id, headers=auth))
job = payload.get("job", payload)
if job["status"] == "succeeded":
break
if job["status"] in ("failed", "cancelled"):
raise RuntimeError("Conversion did not succeed")
time.sleep(2)
else:
raise TimeoutError("Job still pending")
with urlopen(Request(
base + "/v1/jobs/" + job_id + "/download?format=md", headers=auth
), timeout=60) as response:
Path("output.md").write_bytes(response.read())
The CLI uses the same conversion contract, but was not executed for this guide. Its documented command was checked against the supplied install snapshot. 18
The mixed document's scanned passage is present in the archived download. The local configurations without OCR left it unread. The equation output placed a literal caret inside a font command where the source used an exponent. 1011
Output from our equation sample, unedited:
$$
\[\mathsf{E}=\mathsf{m}\mathsf{c}\mathsf{^2}\]
$$
| Failure condition | Visible result | Response |
|---|---|---|
| An expression must retain its mathematical notation | The exponent syntax changes in the exported expression | Correct that expression against the source before using it as data |
| A consumer expects pipe tables only | The result contains HTML table markup | Preserve or parse that table format instead of discarding the tags |
| A grouped header must become named fields | Labels appear without an explicit destination-field mapping | Map the parent and leaf labels together |
Accept text only after its relationships survive
Accept a text export when its sentences, labels and expressions still carry the relationships the downstream task needs.
For a search index using simple prose, native extraction is adequate when the exported sentences remain in order. For records that attach amounts to column names, retain the table representation until grouped labels have an explicit mapping. For image text, an unresolved body passage keeps that part of the document incomplete even when other pages produced useful content. 11
The controlled column pair adds a document-level acceptance condition: include the document's other page shapes when evaluating a native extraction route. The isolated page gave a readable result, while the same page followed another route inside the larger file. 211
How we tested
The results apply to these synthetic English PDFs and the implementations and settings listed here. 1415
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.
The shared corpus has eight provided PDF fixtures. We added three diagnostic variants for the document-composition question. Markovo has archived results for all eight provided fixtures, and no result for the three added variants. We did not submit API conversions during this session. Its archived job creation dates are 2026-10-06. Local execution and rescoring took place on 2026-11-08. 101116
Corpus and versions
| File | Shape represented |
|---|---|
lab/corpus/prose-single.pdf |
Selectable prose |
lab/corpus/table-simple.pdf |
A flat grid table |
lab/corpus/table-merged-header.pdf |
A parent header spanning leaf columns |
lab/corpus/two-column.pdf |
Prose in adjacent columns |
lab/corpus/scan-image.pdf |
Image-only text |
lab/corpus/mixed.pdf |
Native prose, a table and a scanned page |
lab/corpus/equation.pdf |
Linear text expressions, including exponents and subscripts |
lab/corpus/rotated-header.pdf |
A table with rotated header text |
lab/corpus/columns-plus-table.pdf |
The original column page with a table appended |
lab/corpus/columns-wide.pdf |
The same paragraph text placed around a wider column gap |
lab/corpus/columns-wide-plus-table.pdf |
The unchanged wider-gap page with the same table appended |
Each PDF has an adjacent .truth.json file. For appended-table variants, the truth scores only the unchanged column paragraphs. The table is an intervention, not an added scoring target. Construction and fitting checks are in lab/run_local.py. The original narrow-gap pair already failed sentence recovery before the append. 1116
Local Python was 3.11.14. MarkItDown was 0.1.8 with plugins disabled. Its installed dependencies included pdfplumber 0.11.10 and pdfminer.six 20260107. PyMuPDF4LLM, PyMuPDF and PyMuPDF-Layout were 1.28.2. The layout call used page_chunks=True, use_ocr=False. Source files and hashes accompany lab/environment.json. The public PyMuPDF4LLM API page had moved to PyMuPDF 2.0 when accessed. The executable examples use the included PyMuPDF4LLM 1.28.2 source, not parameters inferred from the PyMuPDF 2.0 documentation. 24514
Markovo's archive records rate_card_version=2026-09-19.v3-media-unified. This is a billing-contract identifier, not a software version. Cached elapsed_s=0 placeholders were changed to null in the working scoring input. Remote conversion times are unavailable. Marker, Docling and Pandoc were not executed for this guide. Their pre-existing non-scope archives were excluded from the scoring input. 11
Commands and output files
Run these commands from the repository root, using the supplied environment and corpus. No package installation or network is needed for the local experiments. The final command replays the API example offline as well as executing the local snippets on lab/sample.pdf. It does not test live authentication, upload acceptance or current service behavior. The CLI was not executed for this guide. 121618
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-11-08-markovo-pdf-to-text-convert/lab/run_local.py
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python tools/lab_score.py --lab runs/2026-11-08-markovo-pdf-to-text-convert/lab --out runs/2026-11-08-markovo-pdf-to-text-convert/lab/scores.json --markdown runs/2026-11-08-markovo-pdf-to-text-convert/lab/scores.md
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-11-08-markovo-pdf-to-text-convert/lab/summarize.py
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-11-08-markovo-pdf-to-text-convert/lab/check_examples.py
Raw outputs are lab/markitdown/<sample>.md, lab/pymupdf4llm/<sample>.md and, for the provided fixtures, lab/markovo/<sample>.md. Each service output has an adjacent JSON response snapshot. The article excerpts come from lab/markitdown/columns-wide-plus-table.md, lab/pymupdf4llm/table-merged-header.md and lab/markovo/equation.md, without editing. Snippet outputs are lab/examples/markitdown.md, lab/examples/pymupdf4llm.md and the offline replay output lab/examples/markovo.md. 12
What the scores measure
The following table copies the applicable fields from lab/scores.json. n/a means that the scorer does not define that measure for the fixture, or that an elapsed time was unavailable. Every scoped Markovo row is included. There is no Markovo score for the added fixtures. 1113
| Tool | Sample | prose_recall | reading_order | table_rows_intact | table_header_intact | table_pipe_detected | pages_covered | scan_text_recall | equation_recall | equation_recall_exact | elapsed_s |
|---|---|---|---|---|---|---|---|---|---|---|---|
| markovo | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.5 | 0.0 | n/a |
| markovo | mixed | 1.0 | n/a | 1.0 | 1.0 | false | 1.0 | 1.0 | n/a | n/a | n/a |
| markovo | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a |
| markovo | rotated-header | n/a | n/a | 1.0 | 1.0 | false | n/a | n/a | n/a | n/a | n/a |
| markovo | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 1.0 | n/a | n/a | n/a |
| markovo | table-merged-header | n/a | n/a | 1.0 | 1.0 | false | n/a | n/a | n/a | n/a | n/a |
| markovo | table-simple | n/a | n/a | 1.0 | 1.0 | false | n/a | n/a | n/a | n/a | n/a |
| markovo | two-column | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a |
| markitdown | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.017338 |
| markitdown | table-simple | n/a | n/a | 1.0 | 1.0 | true | n/a | n/a | n/a | n/a | 0.006538 |
| markitdown | table-merged-header | n/a | n/a | 1.0 | 0.0 | true | n/a | n/a | n/a | n/a | 0.008539 |
| markitdown | two-column | 0.1111 | 0.8 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.029278 |
| markitdown | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 0.0 | n/a | n/a | 0.002742 |
| markitdown | mixed | 1.0 | n/a | 1.0 | 1.0 | true | 0.6667 | 0.0 | n/a | n/a | 0.015648 |
| markitdown | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 1.0 | 1.0 | 0.007137 |
| markitdown | rotated-header | n/a | n/a | 1.0 | 0.0 | true | n/a | n/a | n/a | n/a | 0.005923 |
| markitdown | columns-plus-table | 0.1111 | 0.8 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.045051 |
| markitdown | columns-wide | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.029356 |
| markitdown | columns-wide-plus-table | 0.2222 | 0.8 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.025327 |
| pymupdf4llm | prose-single | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.074414 |
| pymupdf4llm | table-simple | n/a | n/a | 1.0 | 1.0 | true | n/a | n/a | n/a | n/a | 0.073584 |
| pymupdf4llm | table-merged-header | n/a | n/a | 1.0 | 0.0 | true | n/a | n/a | n/a | n/a | 0.055571 |
| pymupdf4llm | two-column | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.050098 |
| pymupdf4llm | scan-image | n/a | n/a | n/a | n/a | n/a | n/a | 0.0 | n/a | n/a | 0.092993 |
| pymupdf4llm | mixed | 1.0 | n/a | 1.0 | 1.0 | true | 0.6667 | 0.0 | n/a | n/a | 0.19074 |
| pymupdf4llm | equation | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.75 | 0.75 | 0.031925 |
| pymupdf4llm | rotated-header | n/a | n/a | 1.0 | 0.0 | true | n/a | n/a | n/a | n/a | 0.05743 |
| pymupdf4llm | columns-plus-table | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.109776 |
| pymupdf4llm | columns-wide | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.053987 |
| pymupdf4llm | columns-wide-plus-table | 1.0 | 1.0 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | 0.105586 |
prose_recall matches normalized truth sentences of at least four words. reading_order checks increasing positions of adjacent paragraph-prefix anchors. Missing anchors fail a pair. It does not prove that all sentences between the anchors are intact. The wider-gap MarkItDown control retained 18/18 sentences alone and 4/18 with an appended table, even while the latter's anchor-order score remained 0.8. 1113
table_rows_intact looks for all strings of a truth row on the same physical output line. table_header_intact does the same for the leaf labels. It does not test a spanning parent header's meaning. table_pipe_detected identifies pipe-table syntax. An HTML table serialized on one line can satisfy the row and leaf-header checks without proving cell boundaries or grouped-header semantics. 1113
pages_covered checks mixed-document page anchors. scan_text_recall applies the sentence rule to image-text truth. The mixed fixture's scan sentences were 0/2 in both local configurations and 2/2 in the archive. equation_recall normalizes mathematical delimiters, font wrappers and defined escapes before matching. It retained 4/4 expressions for MarkItDown, 3/4 for PyMuPDF4LLM and 2/4 for Markovo. These are recoverability checks, not a visual typesetting evaluation. 1113
equation_recall_exact retains the scorer's older plain-text comparison. It normalizes case, whitespace and Markdown formatting characters, but leaves LaTeX commands in place. 1113
lab/summarize.py adds integer numerators and denominators under counts without replacing the scorer's metric fields. Its table_cells_anywhere is only a global substring count, not a cell-position test. Single local elapsed times include the work measured by the runner for each call. They are not a repeated benchmark or a remote-speed comparison. 111416
What the API snapshots establish
The mixed fixture has status=succeeded, pages_total=3 and job-level pages_ocr=3. Its job billing metrics report pagesOcr=1, while the estimate's billing_metrics.ocrPageIndexes is [2]. The image-only fixture reports one OCR page consistently, but native-text fixtures have similar job-versus-billing disagreements. We cannot reconstruct an exact final per-page OCR trace from these inconsistent counters. The scan passage's presence is observable in the downloaded text. quality_score=0.9 is a service field, not the accuracy measured by this guide. 1011
The controlled append experiment reproduces the failure pattern reported in issue 2580 using newly constructed fixtures and the installed source. It does not rerun the issue author's original PDF or establish a result for every multi-column layout. The experiments cover no handwriting, damaged scans, complex typeset mathematics or downstream RAG quality. 31116
Sources
- MarkItDown v0.1.8 README
- Installed MarkItDown PDF converter source
- Reported document-composition column regression
- Public API documentation after the PyMuPDF 2.0 migration
- Installed PyMuPDF4LLM 1.28.2 wrapper
- Provided product capability and page-ownership snapshot
- Archived mixed-PDF API response
- Scorer results, integer counts and API provenance
- Local snippet execution and offline API replay
- Scorer implementation and metric definitions
- Runtime, package versions and source hashes
- Provided synthetic PDF fixture descriptions
- Controlled fixture construction and local execution
- Provided Markovo API contract snapshot
- Provided Markovo CLI contract snapshot


