One Open Source Project a Day (Part 50): MarkItDown - Microsoft's Open-Source File to Markdown Converter Supporting PDF, Office, Images, Audio and 15+ Formats

Deep dive into MarkItDown, Microsoft's lightweight Python tool for converting PDF, PowerPoint, Word, Excel, images, audio, HTML, CSV/JSON/XML, ZIP, YouTube URLs, EPUB and more to Markdown, designed specifically for LLMs and text analysis pipelines

·9 min read·Tool Recommendations
open-sourceMarkItDownMicrosoftMarkdownfile conversionPythonLLMOCR

Introduction

"Convert various files to Markdown for use with LLMs and related text analysis pipelines."

This is Part 50 of the "One Open Source Project a Day" series. Today's project is MarkItDown (GitHub).

Need to convert PDF, Word, PPT, Excel files to Markdown for LLM use? Manual conversion is inefficient and loses formatting? MarkItDown is Microsoft's open-source lightweight Python tool for converting various files and Office documents to Markdown: supports PDF, PowerPoint, Word, Excel, images, audio, HTML, CSV/JSON/XML, ZIP, YouTube URLs, EPUB and 15+ formats, designed specifically for LLMs and text analysis pipelines, preserves important document structure (headings, lists, tables, links, etc.), supports plugin system, Azure Document Intelligence, LLM image descriptions.

Why it matters:

  • 🚀 Lightweight Tool: Python 3.10+, simple and easy to use
  • 📚 15+ Format Support: PDF, Office, images, audio, HTML, ZIP, YouTube, EPUB, and more
  • 🎯 Designed for LLMs: Preserves document structure, Markdown format, token-efficient
  • 🔌 Plugin System: Supports third-party plugins to extend functionality
  • ☁️ Azure Integration: Supports Azure Document Intelligence
  • 🧠 LLM Enhancement: Supports LLM image descriptions (OpenAI GPT-4o, etc.)
  • 🐳 Docker Support: Containerized deployment

What You'll Learn

  • MarkItDown's positioning and "designed for LLMs" philosophy
  • Supported input formats and conversion capabilities
  • Plugin system: How to develop and use third-party plugins
  • Azure Document Intelligence integration
  • LLM image description functionality
  • Comparison with similar tools (textract, pandoc, etc.)

Prerequisites

  • Basic Python 3.10+ usage
  • Basic understanding of Markdown format
  • Basic knowledge of LLMs and text analysis (optional)

Project Background

Project Overview

MarkItDown is Microsoft's open-source lightweight Python tool for converting various files to Markdown, designed specifically for LLMs and text analysis pipelines. It is most comparable to textract, but focuses on preserving important document structure and content as Markdown (including: headings, lists, tables, links, etc.).

Core Features:

  • Lightweight: Python 3.10+, simple and easy to use
  • Multi-Format Support: Supports 15+ input formats
  • Structure Preservation: Preserves document structure (headings, lists, tables, links, etc.)
  • Designed for LLMs: Markdown format, token-efficient, natively supported by mainstream LLMs
  • Plugin System: Supports third-party plugins to extend functionality
  • Azure Integration: Supports Azure Document Intelligence
  • LLM Enhancement: Supports LLM image descriptions

Core Problems Solved:

  • File format conversion requires manual operations, low efficiency
  • Format loss after conversion, unclear structure
  • LLMs need structured Markdown format
  • Different formats need different tools, high learning cost

Target Users:

  • Developers who need to convert files to Markdown for LLM use
  • Teams building text analysis pipelines
  • Users who need batch document processing
  • Users who need OCR and image recognition

Author/Team

  • Team: Microsoft (GitHub)
  • Background: Developed and maintained by Microsoft AutoGen Team
  • Philosophy: Designed specifically for LLMs and text analysis pipelines
  • Website: PyPI package, open-source on GitHub

Project Statistics

Tech Stack:

  • Language: Python (99.7%), Dockerfile (0.3%)
  • Python Version: 3.10+
  • Core Features: Plugin system, Azure Document Intelligence, LLM image descriptions

Core Features

Core Purpose

MarkItDown's core purpose is to convert various files to Markdown, designed specifically for LLMs and text analysis pipelines, enabling users to:

  1. File Format Conversion: PDF, Office, images, audio, etc. → Markdown
  2. Structure Preservation: Preserves document structure (headings, lists, tables, links, etc.)
  3. LLM-Friendly: Markdown format, token-efficient, natively supported by mainstream LLMs
  4. Batch Processing: Supports ZIP file batch conversion
  5. OCR Support: Image OCR, scanned PDF OCR
  6. Audio Transcription: Automatic transcription of audio files to text

Use Cases

  1. LLM Document Processing

    • Convert PDF, Word, PPT to Markdown for LLM analysis
    • Preserve document structure, improve LLM understanding accuracy

  2. Text Analysis Pipelines

    • Build text analysis pipelines, unify input formats
    • Batch process multiple format documents

  3. Document Digitization

    • Scanned PDF OCR conversion to Markdown
    • Image OCR text extraction

  4. Content Extraction

    • YouTube video subtitle extraction
    • Audio file transcription

  5. Batch Conversion

    • ZIP file batch conversion
    • Multi-format document unified processing

Quick Start

Installation:

# Install all optional dependencies
pip install 'markitdown[all]'
 
# Or install only specific format dependencies
pip install 'markitdown[pdf, docx, pptx]'

Command-Line Usage:

# Basic usage
markitdown path-to-file.pdf > document.md
 
# Specify output file
markitdown path-to-file.pdf -o document.md
 
# Pipe input
cat path-to-file.pdf | markitdown

Python API:

from markitdown import MarkItDown
 
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

Docker Usage:

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

Key Features

  1. Supported Input Formats (15+ types)

    • 📄 PDF: Supports scanned OCR (requires Azure Document Intelligence or plugin)
    • 📊 PowerPoint: .pptx file conversion
    • 📝 Word: .docx file conversion
    • 📈 Excel: .xlsx, .xls file conversion
    • 🖼️ Images: JPEG/PNG/GIF, supports EXIF metadata and OCR
    • 🎵 Audio: WAV/MP3, supports EXIF metadata and speech transcription
    • 🌐 HTML: Web content conversion
    • 📊 Structured Data: CSV, JSON, XML
    • 📦 ZIP: Batch processing of archive contents
    • 📺 YouTube URLs: Video subtitle extraction
    • 📚 EPUB: Ebook conversion
    • 📧 Outlook: Email message conversion (requires [outlook] dependency)

  2. Optional Dependencies

    • [all]: Install all optional dependencies
    • [pptx]: PowerPoint file support
    • [docx]: Word file support
    • [xlsx]: Excel file support
    • [xls]: Legacy Excel file support
    • [pdf]: PDF file support
    • [outlook]: Outlook message support
    • [az-doc-intel]: Azure Document Intelligence support
    • [audio-transcription]: Audio transcription support
    • [youtube-transcription]: YouTube video subtitle extraction support

  3. Plugin System

    • Supports third-party plugins to extend functionality
    • Plugins disabled by default, must be explicitly enabled
    • Search plugins using #markitdown-plugin tag
    • Example plugin: markitdown-ocr (OCR support)

  4. Azure Document Intelligence

    • Use Microsoft Document Intelligence for conversion
    • Command-line: markitdown path-to-file.pdf -o document.md -d -e "<endpoint>"
    • Python API: MarkItDown(docintel_endpoint="<endpoint>")

  5. LLM Image Descriptions

    • Use LLMs (e.g., OpenAI GPT-4o) to generate image descriptions
    • Supports pptx and image files
    • Provide llm_client and llm_model parameters

  6. MCP Server

    • Provides MCP (Model Context Protocol) server
    • Can integrate with LLM applications like Claude Desktop
    • See markitdown-mcp for details

Project Advantages

ComparisonMarkItDowntextractpandoc
Positioning✅ Designed for LLMs⚠️ General text extraction⚠️ Document conversion
Structure Preservation✅ Preserves Markdown structure⚠️ Plain text✅ Preserves format
LLM-Friendly✅ Markdown, token-efficient⚠️ Plain text⚠️ Other formats
Plugin System✅ Supported❌ None⚠️ Limited
Azure Integration✅ Supported❌ None❌ None
LLM Enhancement✅ Image descriptions❌ None❌ None
Batch Processing✅ ZIP support⚠️ Limited⚠️ Limited
Learning Curve✅ Simple and easy⚠️ Medium⚠️ Complex

Why Choose MarkItDown?

  • Designed for LLMs: Markdown format, token-efficient, natively supported by mainstream LLMs
  • Structure preservation: Preserves document structure (headings, lists, tables, links, etc.)
  • Multi-format support: Supports 15+ input formats
  • Plugin system: Supports third-party plugins to extend functionality
  • Microsoft maintained: 90.7k stars, continuously updated

Deep Dive

Architecture Design

MarkItDown uses a modular + plugin-based architecture design:

Core Components:

MarkItDown
├── DocumentConverter (Document Converters)
│   ├── PDFConverter
│   ├── PPTXConverter
│   ├── DOCXConverter
│   ├── XLSXConverter
│   ├── ImageConverter
│   ├── AudioConverter
│   ├── HTMLConverter
│   └── ... (Other converters)
├── Plugin System
│   ├── markitdown-ocr (OCR plugin)
│   └── ... (Third-party plugins)
├── Azure Integration
│   └── Document Intelligence
└── LLM Integration
    └── Image Description

Design Principles:

  • Modular: Each format has an independent converter
  • Plugin-Based: Supports third-party plugins to extend functionality
  • Optional Dependencies: Install on demand, reduce dependency conflicts
  • Stream Processing: Supports file stream input, no temporary files created

Why Markdown?

Markdown Advantages:

  1. Close to Plain Text: Minimal markup, easy to read
  2. Structure Preservation: Headings, lists, tables, links, and other structural information
  3. Native LLM Support: Mainstream LLMs (e.g., GPT-4o) natively support Markdown
  4. Token-Efficient: Markdown conventions are highly token-efficient
  5. Widely Used: LLM training data contains vast amounts of Markdown-formatted text

Plugin System

Plugin Development:

Refer to packages/markitdown-sample-plugin to develop plugins.

Plugin Usage:

# List installed plugins
markitdown --list-plugins
 
# Enable plugins
markitdown --use-plugins path-to-file.pdf

markitdown-ocr Plugin:

from markitdown import MarkItDown
from openai import OpenAI
 
md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

The plugin adds OCR support to PDF, DOCX, PPTX, XLSX converters, using LLM Vision to extract text from embedded images, no new ML libraries or binary dependencies required.

Azure Document Intelligence

Setting Up Azure Document Intelligence:

  1. Create Azure Document Intelligence resource
  2. Get endpoint URL and key
  3. Use -d -e "<endpoint>" parameter

Command-Line Usage:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Python API:

from markitdown import MarkItDown
 
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

LLM Image Descriptions

Using LLMs to Generate Image Descriptions:

from markitdown import MarkItDown
from openai import OpenAI
 
client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="optional custom prompt"
)
result = md.convert("example.jpg")
print(result.text_content)

Supported File Types:

  • PPTX: Extract images from slides and generate descriptions
  • Image files: Directly generate image descriptions

Stream Processing

v0.1.0 Breaking Changes:

  • convert_stream() now requires a binary file-like object (e.g., a file opened in binary mode, or io.BytesIO object)
  • DocumentConverter class interface changed to read from file-like streams rather than file paths
  • No temporary files are created anymore

Advantages:

  • Higher memory efficiency
  • Supports pipe input
  • Suitable for batch processing

MCP Server

MarkItDown provides an MCP (Model Context Protocol) server that can integrate with LLM applications like Claude Desktop.

See markitdown-mcp project for details.

Project Links and Resources

Official Resources

Related Resources

Target Audience

  • LLM Developers: Need to convert files to Markdown for LLM use
  • Text Analysis Engineers: Building text analysis pipelines
  • Document Processing Users: Need batch processing of multiple format documents
  • OCR Users: Need image and scanned PDF OCR
  • Content Extraction Users: Need to extract content from YouTube, audio, etc.

Learning Value:

  • ✅ Best practices for file format conversion
  • ✅ Markdown format applications in LLMs
  • ✅ Plugin system design and implementation
  • ✅ Azure Document Intelligence integration
  • ✅ LLM image description applications
  • ✅ Stream processing and batch processing

Visit my homepage for more useful knowledge and interesting products

← Back to Blog