$ show microsoft/markitdown
MarkItDown is a Python library and CLI tool that converts a wide variety of file formats (PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, EPUB, Outlook MSG, images, audio, YouTube, RSS, IPYNB, ZIP, and more) into Markdown. Its primary production use is preparing documents for LLM ingestion, agent workflows, and text analysis pipelines. The architecture is a monorepo containing the core `markitdown` package, an OCR extension (`markitdown-ocr`) that uses LLM Vision for image text extraction, an MCP server (`markitdown-mcp`) exposing conversion as a tool for AI agents, and a sample plugin for third-party converters. The core library uses a plugin system based on `importlib.metadata.entry_points` to register converters, each implementing a `DocumentConverter` base class with `accepts()`/`convert()` methods and a priority-based dispatch. The main entry points are the `MarkItDown` class (Python API), the `markitdown` CLI, and the MCP server's `convert_to_markdown` tool. Data flows from local files, streams, HTTP responses, or URIs through converter selection (by MIME type, extension, or content inspection) to produce Markdown output. External dependencies include many optional format-specific libraries (pdfminer.six, python-docx, python-pptx, openpyxl, etc.), external binaries (exiftool, ffmpeg), cloud APIs (Azure Document Intelligence, Azure Content Understanding), and an OpenAI-compatible LLM client for image captioning and OCR.
The LLM identified 5 files worth highlighting for reuse:
Defines the `DocumentConverter` abstract base class and `DocumentConverterResult` dataclass. Each converter implements `accepts(stream, stream_info) -> bool` and `convert(stream, stream_info) -> DocumentConverterResult`. Converters are registered with a priority value; the engine sorts by priority and tries each in order. This pattern is cleanly isolated, versioned, and can be extracted to build any file-to-text conversion pipeline.
A frozen dataclass that encapsulates file stream metadata: MIME type, file extension, charset, source URL, and other properties. Provides a `copy_and_update()` method for creating modified copies. This pattern is reusable in any system that needs to pass immutable stream metadata through a processing pipeline.
Converts Office Math Markup Language (OMML) from DOCX files into LaTeX. Handles a wide range of mathematical constructs (fractions, radicals, integrals, matrices, accents, etc.) by parsing the XML and emitting LaTeX. This is a non-trivial, self-contained module that could be reused in any project needing to extract math from DOCX documents.
Extends the `markdownify` library's `MarkdownConverter` to add URI escaping, data URI truncation, lazy-load `data-src` handling, and custom table processing. Demonstrates how to safely extend an HTML-to-Markdown converter for edge cases encountered in real-world web content. The pattern of subclassing and overriding specific conversion methods is reusable for any HTML sanitization pipeline.
Implements `LLMVisionOCRService`, which uses an OpenAI-compatible LLM Vision API to extract text from images embedded in documents. Includes image caching per conversion, fallback to native rendering on failure, and a clean interface that can be injected into any converter via the `_image_to_html` hook. This pattern is reusable for adding LLM-based OCR to any document processing pipeline.