markitdown

Converts 15+ document formats (DOCX, XLSX, PPTX, PDF, HTML, RSS, MSG, ZIP, EPUB, images, audio) to Markdown by routing each format through a priority-based converter registry that selects the appropriate specialized converter. The system preserves structural semantics (headings, lists, tables, links) rather than extracting raw text, maintaining hierarchical organization and relationships for downstream LLM ingestion and semantic analysis.

Implements a modular converter registry that automatically detects input format (via file extension, MIME type, or stream inspection) and routes to the appropriate specialized converter based on priority rules. The registry supports both built-in converters and dynamically registered plugins, allowing third-party extensions without modifying core code. Format detection uses a fallback chain: explicit format hints → file extension → MIME type → stream content inspection.

Provides an extensible plugin architecture where third-party converters implement the DocumentConverter interface (convert(uri, **kwargs) -> DocumentConverterResult) and register with the converter registry. Plugins are discovered and loaded at runtime, allowing custom format support without modifying core code. The system validates plugin contracts and handles registration priority for format conflicts.

Exposes MarkItDown as a Model Context Protocol (MCP) server, enabling integration with AI assistants (Claude Desktop, etc.) that support MCP. The server implements MCP resource and tool interfaces, allowing assistants to invoke document conversion as a native capability. This enables AI assistants to convert documents on behalf of users without leaving the chat interface.

Provides a CLI entry point (markitdown command) for batch processing documents from the shell. Supports reading from file paths, URLs, or stdin, and outputs Markdown to stdout or files. The CLI integrates with shell pipelines, enabling document conversion as part of larger automation workflows. Supports configuration via command-line flags and environment variables.

Exposes MarkItDown as a Python library via the MarkItDown class, enabling programmatic integration into Python applications, LangChain agents, and AutoGen workflows. The API accepts file paths, streams, or URIs and returns DocumentConverterResult objects containing Markdown content and metadata. Supports custom configuration, error handling, and integration with Python-based document processing pipelines.

Handles various input URI formats (file paths, HTTP/HTTPS URLs, file:// URIs) with automatic format detection based on file extension, MIME type, or content inspection. The system resolves URIs to streams, handles redirects and authentication where applicable, and routes to the appropriate converter. Supports both local and remote document sources transparently.

Implements structured exception handling that captures conversion errors with detailed context (file type, converter used, error location) and provides recovery suggestions. The system distinguishes between recoverable errors (format not supported, missing optional dependency) and fatal errors (corrupted file, network timeout). Error messages include actionable guidance for users.

Provides Docker configuration for deploying MarkItDown as a containerized service, enabling scalable document conversion infrastructure. The Docker image includes all dependencies and optional services (Azure Document Intelligence, LLM APIs), allowing deployment to container orchestration platforms (Kubernetes, Docker Compose). Supports environment variable configuration for API credentials and service endpoints.

Extracts content from DOCX, XLSX, and PPTX files using python-docx, openpyxl, and python-pptx libraries respectively, preserving document structure (headings, lists, tables, text formatting) as Markdown semantic elements. The converters parse the underlying XML structure of Office Open XML format to reconstruct hierarchical organization, maintaining heading levels, list nesting, table layouts, and hyperlinks in Markdown syntax.

Extracts text and structure from PDFs using pdfplumber (text-based extraction) with optional integration to Azure Document Intelligence for advanced OCR, layout analysis, and table detection. The system detects whether a PDF is text-based or scanned and routes to the appropriate extraction method. Azure integration enables extraction of text from image-heavy PDFs and detection of complex table structures that text-only extraction would miss.

Extracts content from web pages (HTML), RSS feeds, and YouTube videos by fetching remote content via HTTP requests and parsing with BeautifulSoup (HTML) or specialized feed parsers (RSS). The system handles URL resolution, follows redirects, extracts main content while filtering navigation/ads, and converts to Markdown. YouTube integration extracts video metadata and transcripts when available.

Processes image files (PNG, JPG, GIF) by either extracting embedded text via OCR or generating descriptive captions using LLM APIs (OpenAI, Anthropic). The system detects image type, optionally calls Azure Document Intelligence for text extraction, and falls back to LLM captioning for visual description. Output includes extracted text and/or generated captions in Markdown format.

Extracts metadata from audio files (MP3, WAV, FLAC, etc.) including title, artist, duration, and bitrate using audio metadata libraries. Optionally integrates with speech-to-text services (Azure Speech, OpenAI Whisper) to generate transcripts. Output includes metadata and transcripts in Markdown format suitable for LLM ingestion.

Extracts content from email message files (MSG format) including headers (from, to, subject, date), body text, and metadata. Recursively processes attachments by routing them through the converter registry, allowing embedded documents to be converted to Markdown. Output includes email metadata and converted attachment content in Markdown format.

Extracts and processes files from ZIP archives by unpacking contents and routing each file through the converter registry based on detected format. Supports nested archives and mixed file types within a single ZIP. Output includes converted content from all archive members in Markdown format, maintaining file organization metadata.

Extracts content from EPUB ebook files by parsing the underlying ZIP structure and XML metadata, preserving chapter organization, headings, and metadata (title, author, publication date). Converts EPUB's XHTML content to Markdown while maintaining reading order and structural hierarchy. Output includes ebook metadata and chapter-organized Markdown content.