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

  1. MarkItDown v0.1.8 README
  2. Installed MarkItDown PDF converter source
  3. Reported document-composition column regression
  4. Public API documentation after the PyMuPDF 2.0 migration
  5. Installed PyMuPDF4LLM 1.28.2 wrapper
  6. Provided product capability and page-ownership snapshot
  7. Archived mixed-PDF API response
  8. Scorer results, integer counts and API provenance
  9. Local snippet execution and offline API replay
  10. Scorer implementation and metric definitions
  11. Runtime, package versions and source hashes
  12. Provided synthetic PDF fixture descriptions
  13. Controlled fixture construction and local execution
  14. Provided Markovo API contract snapshot
  15. Provided Markovo CLI contract snapshot