Microsoft's markitdown: One-Command RAG Document Preprocessing & Java Integration

Why Markdown

Mainstream LLMs like GPT-4o are trained heavily on Markdown, so they naturally output it. Using Markdown for RAG provides two engineering benefits: structure preservation — headings, lists, tables, and links survive conversion, enabling heading-based chunking instead of guessing boundaries on plain text; and token efficiency — Markdown's minimal syntax uses far fewer tokens than HTML, saving real cost at scale.

Unlike traditional extractors such as textract that only pull raw text, markitdown's goal is to retain document structure.

Supported Formats

Office suite (Word, Excel, PowerPoint), PDF, EPub, HTML, CSV, JSON, XML, ZIP archives (auto-traverses contents), Outlook emails, YouTube links (fetches subtitles), images (EXIF + OCR), and audio (speech-to-text). Dependencies are opt-in; for PDF and Office only: pip install 'markitdown[pdf,docx,pptx]' Full install: pip install 'markitdown[all]' (requires Python 3.10+).

Conversion Quality

The critical test is tables. Excel and Word tables convert to standard Markdown tables with aligned columns and clear headers. Since table degradation to plain text destroys retrieval hit rates, preserving tables retains most of a document's value for RAG.

Boundary: the README states output is for text-analysis tools, not high-fidelity human-readable layout. Pixel-perfect PDF reproduction is out of scope.

Batch Preprocessing

Command Line

markitdown contract.pdf -o contract.md
cat contract.pdf | markitdown  # stdin/stdout works

Python API

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
for f in Path("docs").rglob("*"):
    if f.suffix.lower() in {'.pdf', '.docx', '.xlsx', '.pptx'}:
        result = md.convert(str(f))
        out = Path("markdown_out") / f.with_suffix('.md').name
        out.write_text(result.markdown, encoding='utf-8')

A dozen lines processes a whole directory of mixed formats; the resulting Markdown plugs directly into existing chunking and embedding pipelines.

Java Backend Integration

markitdown is Python-only; three practical patterns exist for Java projects.

1. Offline Indexing — CLI Subprocess

RAG document cleaning is typically an offline batch job. Java can spawn a child process:

ProcessBuilder pb = new ProcessBuilder(
    "markitdown", filePath, "-o", outputPath);
pb.redirectErrorStream(true);
Process p = pb.start();
int exitCode = p.waitFor();

Runs once or daily; performance is sufficient without a dedicated service.

2. Online User Uploads — Docker Sidecar Service

The official repo declines web-service code, so wrap a FastAPI endpoint around MarkItDown and containerize:

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < your-file.pdf > output.md

Decouples parsing from the main service, isolating dependencies and resources.

3. Agent File Parsing — markitdown-mcp

Official MCP server package lets MCP-compatible clients (e.g., Claude Code) invoke markitdown directly, giving agents universal file-reading ability.

Security Red Line

markitdown performs I/O with the process's permissions. Never feed untrusted user input directly. Validate paths, restrict URI schemes, and call the narrowest conversion function: use convert_local() for local files only, avoid the permissive convert().

Comparison with Traditional Tools

Apache Tika / PDFBox (Java) : Tika covers many formats and integrates natively, but outputs plain text — losing tables and heading hierarchy, which forces RAG to guess structure. PDFBox is lower-level, requiring manual layout coordinate calculation.

Python stack (python-docx + pdfplumber + pandas) : One library per format, fragmented code, inconsistent output. markitdown unifies them under a single entry point with uniform Markdown output.

Limitations

Complex scanned PDFs exceed the built-in converters. Official escape hatch: integrate Azure Document Intelligence or Content Understanding via the -d flag (cloud API, per-call billing). For on-prem, community plugin markitdown-ocr uses vision models like GPT-4o to extract text from embedded images.

Author's Take

RAG quality splits 50/50 between retrieval strategy and preprocessing quality. The latter has long been treated as grunt work. markitdown turns that half into a standard component: one entry point, unified output, intact structure.

Best fit : teams building knowledge bases or document-cleaning pipelines who struggle with multi-format parsing. Not fit : teams needing pixel-perfect layout for human consumption, or pure-Java shops unwilling to operate a Python sidecar.

Document preprocessing is becoming infrastructure; Microsoft packaging it as a single command is the right direction.

Open Source

https://github.com/microsoft/markitdown