When building RAG or Agent systems, the first step is often described as embedding. In practice, there's a step that comes even earlier: extracting usable text from PDFs, Word documents, and PowerPoint files so the model can process it reliably.
PDFs contain multi-column layouts, tables, and footnotes. PowerPoint files have heading hierarchies and bullet structures. Word documents carry style metadata. Handing raw files to a model produces unpredictable parsing results.
Microsoft's open-source MarkItDown sits at this position in the pipeline. It isn't built for human-facing format conversion or pixel-perfect fidelity. Its job is to compress common file types into Markdown that's friendly for LLM consumption.
The project has 174k+ stars on GitHub (the number changes frequently—check the repo for the current count). Supported formats include:
- Word
- Excel
- PowerPoint
- Images (with EXIF metadata and OCR)
- Audio (with EXIF metadata and transcription)
- HTML, CSV, JSON, XML
- ZIP, EPub
- YouTube links
The design intent is clear: the output isn't a document formatted for human readers. It's structured text formatted for LLMs.
What Problem Does It Solve
Before embedding, three tasks typically need to happen:
- Extract the main content.
- Preserve structure—headings, lists, tables.
- Chunk the result into pieces the model can handle.
MarkItDown handles the first two.
Among similar tools, textract is dated and often outputs plain text, losing structural information. pandoc emphasizes document conversion and fidelity, fitting scenarios where you need output close to the original layout. unstructured is also feature-complete but heavier, with a different abstraction layer.
MarkItDown takes a middle path:
- Lightweight.
- Retains some document structure.
- Outputs Markdown, which LLMs handle well.
- Available as both a CLI and a Python API.
Markdown typically uses fewer tokens than complex HTML or text loaded with formatting markers. Models like GPT-4o also natively understand Markdown headings, lists, tables, and code blocks.
That said, Markdown isn't always the shortest representation. Complex Word styling, PDF headers and footers, and coordinate-based layouts can still introduce noise after conversion. But it provides a stable intermediate format. Downstream chunking, retrieval, and generation can all operate on the same text.
How to Use It
Python 3.10+. Full installation:
pip install 'markitdown[all]'
PDF only:
pip install 'markitdown[pdf]'
Other groups include [docx], [pptx], [xlsx], [audio], and more. No need to install OCR, audio transcription, and every format if you don't need them.
CLI:
markitdown file.pdf > out.md
Python API:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content[:500])
# Restrict input sources: local files only
from markitdown import MarkItDown, convert_local
result = convert_local("report.pdf")
print(result.text_content[:500])
MarkItDown().convert() is the high-level interface that selects a converter based on the input. convert_local() is narrower and handles local files only.
A word of caution on security. The README prominently warns that MarkItDown involves I/O operations with permission risk comparable to Python's open() or requests.get() for network calls. Don't drop it into environments handling untrusted input, arbitrary URLs, or high-privilege Agents just because it's "just a document converter."
How It Works
The core architecture isn't complicated:
- A
MarkItDownclass. - Multiple
Convertersubclasses. - Dispatch based on file extension or MIME type.
- Each Converter handles one format.
PDF routes to PdfConverter, Word to DocxConverter, PowerPoint to PptxConverter, YouTube links to YoutubeConverter.
This design is easier to extend than a monolithic function full of if/else branches. Adding a new format usually means writing a new Converter and wiring it into the dispatch logic.
Three API layers:
- High-level:
MarkItDown().convert() - Mid-level:
convert_local() - Low-level:
convert_stream()
The lower you go, the narrower the permission scope—and the easier it is to clearly distinguish local files, external network sources, and streamed input in your code. For Agents, this distinction matters. Once an Agent can read files, access the network, or handle untrusted links on a user's behalf, permission design becomes a core feature, not an afterthought.
Image and audio paths differ. Images can extract EXIF metadata and run OCR based on configuration. Audio can extract metadata and perform transcription. These paths typically depend on external services. Before deploying, confirm which services, costs, and data flows are involved.
Strengths and Weaknesses
What It Does Well
Broad format coverage. One tool handles PDF, Office, images, audio, web pages, archives, and YouTube links.
Progressive API design. A one-line CLI for simple use; MarkItDown().convert() for integration; convert_local() or convert_stream() when you need to restrict input sources.
Engineering-grade security disclosure. The README doesn't sidestep the risks of local files, network requests, and third-party services.
Installation considers dependency footprint. The full install is simple, but per-format installs keep environments lean.
Where It Falls Short
First, complex layout fidelity doesn't match pandoc. Cross-page tables, footnotes, floating images, intricate headers, and multi-column PDFs may come out in unexpected order after conversion. OCR quality also depends on image text clarity.
Second, image OCR and audio transcription may depend on external services like Azure or OpenAI. For scenarios requiring purely local, CPU-only processing with no data upload, you'll need to bring your own models and dependencies.
Third, Excel isn't meant to be dumped wholesale into a single file. Large workbooks, merged cells, formulas, and hidden sheets can slow things down and bloat the output with irrelevant content. In production, pre-filter sheets, limit row/column ranges, strip formulas, or split by table.
So MarkItDown isn't a pandoc replacement, and it isn't a parser that perfectly reconstructs every document. It's more like the first cleaning stage in a RAG pipeline.
I Tried It
I installed markitdown[pdf,docx,pptx] locally and tested with three files:
- A 20-page financial report PDF with tables.
- A 20-page PowerPoint.
- A 5-page Word document.
Results:
- PDF tables were mostly preserved; heading hierarchy was correct.
- PowerPoint retained its bullet structure.
- Word output was clean, with stable paragraphs and headings.
- PDF: ~2 seconds.
- PowerPoint: ~1 second.
- Word: under 1 second.
Speed varies significantly with file complexity. On my machine, PDF parsing bottlenecks on PyMuPDF page processing. What usually slows down the entire pipeline is large Excel files.
To feed results into RAG, I'd do two things after getting result.text_content: chunk by headings and paragraphs first, then add metadata like table names, page numbers, or filenames. Don't dump a 500-page PDF into a single convert() call and expect stable retrieval quality.
Who Should Use It
Good fit for:
- RAG document preprocessing.
- Data ingestion in Agent toolchains.
- Batch document cleaning.
- Scripts that need to unify PDF, Word, and PowerPoint into Markdown.
- Projects that dispatch converters by file extension or MIME type.
Not a good fit for:
- Pixel-perfect or publication-grade layout fidelity.
- Strictly offline image OCR or audio transcription.
- Whole-file conversion of complex Excel reports.
- Projects needing coordinate-level PDF positioning, reading-order reconstruction, or strict table semantics.
My rule of thumb is straightforward: when feeding text to an LLM, try MarkItDown first; when preserving layout matters most, use pandoc; when you need complex document partitioning and heavier data processing, look at unstructured.
MarkItDown's value isn't in "how many formats it supports." It simplifies how Agents receive the world into a single step: file in, Markdown out.