- name
- markitdown
- description
- Convert various document formats (PDF, Word, PowerPoint, Excel, images, audio, HTML, etc.) to Markdown using Microsoft's markitdown tool. Supports OCR, audio transcription, and YouTube video extraction.
- triggers
MarkItDown
Microsoft's lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines.
Installation
Prerequisites
- Python 3.10+
- Java 11+ (for some converters)
Install via pipx (recommended)
pipx install 'markitdown[all]'Install via pip
pip install 'markitdown[all]'Minimal install (specific formats only)
pip install 'markitdown[pdf,docx,pptx]'Supported Formats
| Format | Extension | Notes |
|---|---|---|
| Preserves structure, tables, links | ||
| Word | .docx | Headings, lists, tables |
| PowerPoint | .pptx | Slides to Markdown |
| Excel | .xlsx, .xls | Table data |
| Images | .png, .jpg, etc. | EXIF metadata + OCR |
| Audio | .wav, .mp3 | Speech transcription |
| HTML | .html, .htm | Web content |
| YouTube | URL | Video transcription |
| ZIP | .zip | Iterates over contents |
| EPub | .epub | E-books |
| Text | .csv, .json, .xml | Text-based formats |
CLI Usage
Basic Conversion
# PDF to Markdown
markitdown document.pdf > output.md
# Word to Markdown
markitdown document.docx -o output.md
# PowerPoint to Markdown
markitdown presentation.pptx -o output.mdPipe Input
cat document.pdf | markitdownImage OCR
markitdown screenshot.png -o text.mdYouTube Video
markitdown "https://youtube.com/watch?v=..." -o transcript.mdPython API Usage
from markitdown import MarkItDown
# Initialize
md = MarkItDown()
# Convert file
result = md.convert("document.pdf")
print(result.text_content)
# Convert from stream
with open("document.pdf", "rb") as f:
result = md.convert_stream(f)
print(result.text_content)Options
| Option | Description | Example |
|---|---|---|
-o, --output | Output file | -o output.md |
--format | Output format (default: markdown) | --format json |
--pages | Specific pages | --pages "1,3,5-7" |
--image-output | Image handling | --image-output external |
--quiet | Suppress output | --quiet |
MCP Server
MarkItDown provides an MCP (Model Context Protocol) server for integration with LLM applications:
pip install markitdown-mcpBest Practices
- Batch processing: Process multiple files in one call for efficiency
- Format selection: Use minimal install if only specific formats needed
- OCR quality: Ensure 300 DPI+ for scanned documents
- Output review: Always verify Markdown output for complex documents
Troubleshooting
Java not found
Install Java 11+:
# macOS
brew install openjdk@17
# Ubuntu
sudo apt install openjdk-17-jdkPermission denied
Use pipx or virtual environment:
python3 -m venv ~/.venvs/markitdown
source ~/.venvs/markitdown/bin/activate
pip install 'markitdown[all]'References
- GitHub: https://github.com/microsoft/markitdown
- PyPI: https://pypi.org/project/markitdown/
- MCP Server: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp