4. MarkItDown Against Pandoc, Docling and pdftotext, and Who Should Actually Adopt It

Three parts in, we have a clear picture of MarkItDown on its own: good at Word, EPUB, YouTube and guessing file types, and quietly unreliable on PDFs, scans and audio. Now the question that decides whether you should use it: compared with what? We ran the same documents through the three tools people most often reach for instead. Pandoc is the veteran universal converter. Docling is IBM's machine-learning document parser. pdftotext from Poppler is the boring command-line baseline. Then we give our verdict on who should adopt MarkItDown.

Same Mac as before: Apple M4 Pro, 48 GB, macOS 26.5.1. Versions: MarkItDown 0.1.8 (and 0.1.5 where noted), Pandoc 3.11, Docling 2.130.0, pdftotext 26.04.0. Warm timings unless we say otherwise.

Install	Time	Disk
MarkItDown [all], via uv	26.97 s	318 MB
Pandoc, via Homebrew	18.08 s	Not measured
Docling, via uv	81.16 s	1.1 GB, plus 530 MB of models on first run
pdftotext (Poppler)	Already installed, not timed	Part of Poppler

Installing the challengers

brew install pandoc poppler
cd ~/markitdown-test
uv venv --python=3.12 dl
uv pip install --python dl/bin/python docling
dl/bin/docling --version

Docling's environment is 1.1 GB, of which PyTorch alone is 554 MB. The first time you convert anything it also downloads two layout models from Hugging Face, 530 MB, with no account or key needed. Our first Docling run on Publication 334 took 182.89 seconds, including that download. The second took 108.03.

Word, PowerPoint and EPUB: MarkItDown against Pandoc

Pandoc cannot read PDFs at all (it says so plainly: Pandoc can convert to PDF, but not from PDF), so on Office files it is the fair comparison.

pandoc docs/lp1-directions.docx -t gfm -o out/lp1.pandoc.md
pandoc docs/agfs-slides.pptx -t gfm -o out/slides.pandoc.md
pandoc docs/frankenstein.epub -t gfm -o out/frankenstein.pandoc.md

Document	MarkItDown 0.1.8	Pandoc 3.11
GOV.UK Word file, time	0.46 s	0.42 s
Its merged-cell table	Markdown pipe table	Raw HTML <table> with colgroup
GOV.UK deck, bullet points kept	0	30
Frankenstein EPUB, time	0.49 s	0.56 s
World Bank .xls	Converted	Unknown input format 'xls'
GOV.UK .ods	Unsupported	Unknown input format 'ods'

This is closer than we expected. Pandoc preserves structure better: it kept every bullet in the slide deck where MarkItDown flattened them into plain lines, and it can also read .odt text documents, which MarkItDown cannot. But when a table has merged cells, Pandoc falls back to raw HTML, which is correct for a human-readable document and noisier for an LLM. MarkItDown squeezes it into a pipe table. Pandoc 3.11 reads .xlsx and .pptx but not the older .xls, and neither tool reads LibreOffice spreadsheets.

For EPUB both were good. We did not diff the two Frankenstein outputs line by line, only checked the headings and metadata, so call that one a draw on limited evidence.

PDFs: all four tools, three documents

These are the documents from parts 2 and 3: Publication 334 (57 pages, two columns), the Attention paper (15 pages, one column, many tables), and our scanned W-9 page (an image with no text layer).

dl/bin/docling irs/p334.pdf --to md --output dl-out
dl/bin/docling docs/attention.pdf --to md --image-export-mode placeholder --output dl-out
dl/bin/docling docs/w9-scanned.pdf --to md --output dl-out

	MarkItDown 0.1.8	MarkItDown 0.1.5	Docling	pdftotext
Pub 334, time	4.36 s	6.79 s	108.03 s	0.10 s
Pub 334, sentences intact (canary, of 50)	3	46	37	Reference
Pub 334, headings found	0	0	171	0
Attention paper, words	2,802	5,868	6,183	6,152
Attention paper, glued tokens	397	7	16	2
Attention paper, table rows	72	0	54	0
Attention paper, time	1.25 s	not timed	21.17 s	0.07 s
Scanned W-9, output	1 byte	not tested	922 words	1 byte

For scale, pdftotext took 0.40 seconds for the 142-page Publication 17 and 1.53 seconds for all eleven IRS publications together. We are not giving it a canary score, because it is the canary's reference and would pass itself.

Docling is the only tool here that understands a document. It found 171 headings in Publication 334, where everything else found none, and 28 in the Attention paper. On Table 2 it kept GNMT+RL's training costs on the right row, which MarkItDown 0.1.8 did not. It still flattened the exponents to 1.4·1020, so no tool here gets those right. And it read the scan. With its bundled RapidOCR engine, running locally on the CPU in 8.92 seconds, it produced a structured page: headings, the checkbox list as - [ ] items, and the instructions. The OCR was not clean: "3a" became "38", "is" became "i8", and one checkbox came out as □C corporation. But 922 imperfect words beat 1 byte by a distance.

The price is time and weight. Docling was 25 times slower than MarkItDown 0.1.8 on Publication 334, and about 1,000 times slower than pdftotext. On our 698-page IRS folder, extrapolating from that one file, a single Docling process would need something like 22 minutes. We did not run the whole folder through Docling, so treat that figure as an estimate, not a measurement.

Where MarkItDown has no competition here

Two things in part 2 have no equivalent in the other three tools: turning a YouTube URL into a transcript (13.12 seconds, no key), and fetching a URL straight into Markdown, including a dedicated Wikipedia converter. Add Magika's content sniffing, which correctly handled a spreadsheet saved with a .zip name, and one Python call that accepts almost any file. That combination is the real product. It is why agent frameworks keep reaching for it, and for mixed folders of Office files it earns that.

What broke across the whole course

• Pip on macOS's Python 3.9 "installed" a 2.6 kB placeholder with no code (part 1).
• OpenDocument files fail with a traceback (part 1).
• Scanned PDFs and images return a single newline with exit 0 (part 2).
• PDF text loses its spaces on some pages. Issue #120 has been open since December 2024 (part 2).
• Audio is uploaded to Google through a shared default key, with no notice (part 2).
• Wikipedia rejects the default User-Agent. The CLI and MCP server cannot change it (parts 2 and 3).
• Since 0.1.6, any PDF with one table-like page is read straight across its columns. All eleven IRS publications were scrambled (part 3).

Only two of those seven produced a non-zero exit code: the OpenDocument file and the Wikipedia 403. That is the pattern to remember.

The verdict: who should adopt it

Adopt it if you are a developer feeding an LLM a mixed pile of Word files, slide decks, spreadsheets, EPUBs, web pages and YouTube links, and you want one Python call that figures out what each file is. On those inputs it was fast (under half a second a file, most of it start-up), and its failures were loud. The MIT licence, 186,978 stars and a release roughly every two months mean it is not going anywhere.

Do not use it as your PDF extractor on 0.1.6 to 0.1.8, at least not without the canary from part 3. For prose PDFs, pdftotext was faster and kept the text intact. For PDFs where structure matters (headings, tables, scans), Docling is the better tool, if you can afford about two minutes per 57 pages. Pinning MarkItDown 0.1.5 fixes the text but costs 2,065 MB of memory on a 142-page file.

Do not use it on scans or images unless you pay for a vision model or Azure. Out of the box, it returns nothing and says nothing.

Do not use it on confidential audio. Install without the audio extra so it cannot happen by accident.

Use Pandoc instead if a human will read the output, if you need bullet points and slide structure kept, or if you work with LibreOffice text documents. MarkItDown's own README says it is not built for high-fidelity output for people, and our results agree.

Trust MarkItDown with Office files, check it on PDFs, and never trust its exit code.

One more thing weighs on the verdict. The repo had 368 open pull requests and 327 open issues when we checked, and the whitespace bug is 21 months old with two fix attempts that have not been merged. The project is busy, not abandoned. But fixes arrive slowly, so plan around the bugs you know about rather than waiting for them.

What we did not test

We did not test any paid feature: Azure Document Intelligence, Azure Content Understanding, LLM image captions or the OCR plugin. Any of them may fix the scan problem, and we cannot tell you whether they do. We did not test Docling on Word, PowerPoint or Excel, or on the full IRS folder. We did not test Pandoc on .xlsx or .odt, only confirmed it lists them. We did not test other extractors such as Marker, MinerU or Unstructured. Every number comes from one Apple Silicon Mac, and the PDF results come mostly from one family of US government documents plus one arXiv paper. Your PDFs may behave better or worse, which is exactly why the canary exists.

Cleaning up everything from this course

The Docling models live in the shared Hugging Face cache, so remove only those two rather than the whole folder:

~/markitdown-test/dl/bin/hf cache rm model/docling-project/docling-layout-heron model/docling-project/docling-models --dry-run
~/markitdown-test/dl/bin/hf cache rm model/docling-project/docling-layout-heron model/docling-project/docling-models -y
rm -rf ~/markitdown-test
brew uninstall pandoc

Run the first line on its own first. On our machine the dry run listed 530 MB across the two model repos. Then run the rest. Leave Poppler installed if you took our advice from part 3, because pdftotext is the part of this course we would keep.

Where to go from here

If you build the pipeline from part 3, watch the MarkItDown release notes for a fix to the PDF fallback condition, then rerun canary.py on your own documents before switching PDFs back. If you need structure from PDFs, spend an afternoon with Docling on your ten hardest files and time it yourself. And if you only came for the verdict: MarkItDown is a very good Office-to-Markdown tool that happens to accept PDFs. Treat that last part as a convenience, not a promise.