Markitdown

MarkItDown Document Conversion

Convert files to Markdown using Microsoft's MarkItDown utility.

Installation

Full Installation

pip install 'markitdown[all]'

Selective Installation

pip install 'markitdown[pdf]'                    # PDF only
pip install 'markitdown[docx]'                   # Word documents
pip install 'markitdown[pptx]'                   # PowerPoint
pip install 'markitdown[xlsx]'                   # Excel
pip install 'markitdown[audio]'                  # Audio transcription
pip install 'markitdown[image]'                  # Image OCR
pip install 'markitdown[azure-doc-intelligence]' # Azure AI PDF
pip install 'markitdown[llm]'                    # LLM image descriptions

Command-Line Usage

# Basic conversion
markitdown file.pdf

# Save to file
markitdown file.pdf > output.md
markitdown file.pdf -o output.md

# Batch conversion
for file in *.pdf; do markitdown "$file" > "${file%.pdf}.md"; done

Python API

Basic Usage

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

Stream Processing

with open("file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")

With Azure Document Intelligence

md = MarkItDown(
    azure_doc_intelligence_endpoint="https://your-resource.cognitiveservices.azure.com",
    azure_doc_intelligence_key="your-key"
)

With LLM Image Descriptions

md = MarkItDown(
    llm_model="gpt-4o",
    llm_client=None  # Uses default client
)

Supported Formats

Common Patterns

Batch Processing

import os
from markitdown import MarkItDown

md = MarkItDown()

for filename in os.listdir("input/"):
    if filename.endswith(('.pdf', '.docx', '.pptx')):
        result = md.convert(f"input/{filename}")
        base = os.path.splitext(filename)[0]
        with open(f"output/{base}.md", "w") as f:
            f.write(result.text_content)

Error Handling

try:
    result = md.convert("file.pdf")
    markdown = result.text_content
except Exception as e:
    print(f"Conversion failed: {e}")

Memory-Efficient Processing

with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")

Docker Usage

# Build
docker build -t markitdown:latest .

# Run
docker run --rm -i markitdown:latest < input.pdf > output.md

# With volume
docker run --rm -v $(pwd):/data markitdown:latest /data/file.pdf

Output Format

MarkItDown produces clean, structured Markdown:

# Document Title

## Section Heading

Content with **bold** and *italic* formatting.

- Bullet lists
- Preserved from source

| Table | Headers |
|-------|---------|
| Data  | Values  |

[Links](https://example.com) maintained.

Best Practices

Performance

• Use streams for files >10MB
• Batch process multiple files
• Cache converted results
• Use selective dependencies

Quality

• High-resolution images for OCR
• Well-formatted source documents
• Azure Document Intelligence for complex PDFs
• LLM descriptions for important images

Integration

• Check token counts for LLM limits
• Chunk long documents
• Preserve metadata in context
• Validate output structure

Troubleshooting

Requirements

• Python 3.10+
• Virtual environment recommended
• Optional: Azure subscription for enhanced features
• Optional: OpenAI API for image descriptions

When to Use This Skill

• Converting documents for AI analysis
• Extracting content from PDFs
• Processing Word/PowerPoint files
• Preparing data for language models
• Batch document conversion
• Building document pipelines