MarkItDown: Getting Any File Into Markdown a Model Can Read

Why markdown, and why one tool

A model reads text. Feed it raw HTML and most of the context window goes on markup; feed it a stripped text dump and you lose the headings and lists that told the model what the document's structure was. Markdown is the compromise: light enough to cost almost nothing in tokens, structured enough that a heading stays a heading. The project's own README makes the same point: it targets consumption by text-analysis tools, not high-fidelity conversion for human readers, and names textract as its closest comparison — a useful anchor if you have used that library before.

The second argument is uniformity. A real corpus is a spreadsheet, three Word files, a slide deck and two PDFs. Without a single converter, ingestion becomes a pile of format-specific code, each with its own edge cases and its own way of failing silently on a file nobody tested. MarkItDown is developed by Microsoft, MIT-licensed, and had more than 187,000 GitHub stars at the end of September 2026 — a scale of adoption that says less about conversion quality in the abstract than about how common this exact ingestion problem is across teams building anything RAG-shaped.

Installing it

1. Install with the full feature set — pip install 'markitdown[all]' pulls every optional dependency; installing from source works the same way against the repository checkout.
2. Or install only what you need — pip install 'markitdown[pdf, docx, pptx]' installs dependencies for just those formats, keeping the environment smaller.
3. Run it from the command line — markitdown path-to-file.pdf > document.md, or pipe a file in: cat path-to-file.pdf | markitdown.
4. Or call it from Python — from markitdown import MarkItDown; md = MarkItDown(); result = md.convert("test.xlsx"); print(result.markdown).
5. Or run it in Docker — docker build -t markitdown:latest . then docker run --rm -i markitdown:latest < file.pdf > output.md, useful for a stateless conversion step in a larger pipeline.

What it handles, and how well

Format	Result	Comment
Word documents	Very good	Headings, lists and simple tables survive
Spreadsheets	Good	Sheets become markdown tables; formulas become their values
Presentations	Good	Slide text and notes, without the visual arrangement; can use an LLM for image descriptions
HTML	Good	Useful for pages you already have on disk
Images	Metadata, plus optional LLM description	EXIF metadata is read directly; the built-in LLM-vision path (pptx and image files) needs an OpenAI-compatible client
Text-layer PDFs	Variable	Fine on simple layouts, weak on multi-column pages and complex tables
Scanned PDFs and images	Needs OCR	No text layer means nothing to extract by default — see Tesseract, or the markitdown-ocr plugin below

The Python API accepts llm_client and llm_model arguments to generate image descriptions with an LLM instead of leaving images undescribed — currently limited to PowerPoint and image files. It also exposes max_retries for the underlying OpenAI-compatible client, with a documented default of 2 retries; if every attempt fails, MarkItDown falls back to other applicable converters rather than aborting the whole file.

Extending it: plugins and Azure

Plugins are disabled by default; markitdown --list-plugins shows what is installed, and markitdown --use-plugins path-to-file.pdf turns them on. Third-party plugins are discoverable on GitHub under the #markitdown-plugin hashtag. The project's own markitdown-ocr plugin is the most relevant one for local RAG: it adds OCR to PDF, DOCX, PPTX and XLSX converters by extracting text from embedded images through LLM vision, reusing the same llm_client / llm_model pattern MarkItDown already uses for image descriptions, with no extra ML libraries or binary dependencies. Installing it is pip install markitdown-ocr plus an OpenAI-compatible client; without an llm_client, the plugin still loads but silently skips OCR and falls back to the standard converter.

Beyond plugins, two optional Azure integrations push quality further at the cost of a network call: Azure Document Intelligence (install extra [az-doc-intel], pass a docintel_endpoint) for cloud-based layout extraction, and Azure Content Understanding (extra [az-content-understanding]) for structured field extraction serialized as YAML front matter, plus the only supported path for video and higher-quality audio. Both are billable cloud calls, not local compute, and neither is required for the everyday case of clean office documents — they exist for the harder tail of a corpus, not as a default you should reach for first.

MarkItDown or a layout-aware parser

This is the only comparison that matters, and it is not about quality in the abstract but about your files.

	MarkItDown	Docling
Weight	A small package, no model weights for common formats	Model-based, heavier, GPU helps
Speed	Very fast	Seconds per complex page
Office files	Excellent	Also good
Complex PDF layout	Weak by default	Its reason to exist
Table structure	Basic	Recovered properly
Scanned PDFs	Needs the OCR plugin or an external step	Handled natively
Right when	Born-digital office and web documents	Scanned or visually complex PDFs

A sensible pipeline uses both: route by file type and by whether a PDF has a text layer. Cheap conversion for the 80% that is straightforward, expensive conversion for the rest. Choosing one tool for everything means either wasting compute on simple files or producing garbage on hard ones.

Worth knowing about MarkItDown's own project boundaries: its maintainers explicitly keep the repository to a Python library, a CLI and an MCP package, and list web servers, REST or HTTP APIs, and hosted conversion services as out of scope for contributions. In practice that means if you need a conversion microservice behind an API, you build it yourself on top of the library rather than expecting one from the project — a design choice that keeps the core small and matches its role as a component, not a product.

Placing it in a local stack

1. Detect the type. Office or HTML goes to MarkItDown; a PDF gets checked for a text layer.
2. Convert and cache. Conversion happens once per document version, never per query.
3. Chunk along the markdown structure — by heading, keeping tables intact — rather than by character count.
4. Embed and store, then answer from retrieved passages with a local model. The full picture is in what RAG is.

Readers assembling the rest of a local RAG stack around this ingestion step can compare the pieces side by side in our local RAG toolkit.

Verdict

MarkItDown is the sensible default for the boring majority of a corpus: office files, web pages, anything born digital. It costs almost nothing to run and gets structure right where structure is explicit in the file format, and its plugin and Azure options give it a documented growth path for images, scanned pages, audio and video without switching tools entirely for the whole pipeline. Keep a heavier parser for scanned and visually complex PDFs, route by file type, and cache everything — the combination is both cheaper and better than either tool alone.

Sources

• MarkItDown repository on GitHub — license, stars, releases
• MarkItDown README — install options, plugins, Azure integrations, Python and CLI usage
• markitdown-mcp package — the official MCP server