markitdown

Document to Markdown Conversion

Overview

Convert various document formats to clean Markdown using Microsoft's MarkItDown tool. Optimized for LLM processing, content extraction, and document analysis workflows.

Supported Formats: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx/.xls), Images (with OCR/LLM), HTML, Audio (with transcription), CSV, JSON, XML, ZIP archives, EPubs

Quick Start

Basic Usage

from markitdown import MarkItDown

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

Command Line

# Convert single file
markitdown document.pdf > output.md
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown

🔒 Security Considerations

Before using in production:

• ✅ Validate file types (MIME, not extension)
• ✅ Limit file sizes (prevent DoS)
• ✅ Sanitize file paths (prevent traversal)
• ✅ Protect API keys (never hardcode)
• ✅ Consider data privacy (external services)

See patterns.md for implementation details.

API Key Security

❌ NEVER:

• Hardcode keys in code
• Commit .env files to git
• Log environment variables

✅ ALWAYS:

• Use environment variables: export OPENAI_API_KEY="sk-..." # pragma: allowlist secret
• Use secret management (AWS Secrets Manager, Azure Key Vault)
• Rotate keys regularly

Common Patterns

PDF Documents

# Basic PDF conversion
md = MarkItDown()
result = md.convert("report.pdf")

# With Azure Document Intelligence (better quality)
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("report.pdf")

Office Documents

# Word documents - preserves structure
result = md.convert("document.docx")

# Excel - converts tables to markdown tables
result = md.convert("spreadsheet.xlsx")

# PowerPoint - extracts slide content
result = md.convert("presentation.pptx")

Images with Descriptions

# ✅ SECURE: Using environment variables for API keys
import os
from openai import OpenAI

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("OPENAI_API_KEY not set")

client = OpenAI(api_key=api_key)
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("diagram.jpg")  # Gets AI-generated description

Batch Processing

from pathlib import Path

md = MarkItDown()
documents = Path(".").glob("*.pdf")

for doc in documents:
    result = md.convert(str(doc))
    output_path = doc.with_suffix(".md")
    output_path.write_text(result.text_content)

Installation

# Full installation (all features)
pip install 'markitdown[all]'

# Selective features
pip install 'markitdown[pdf, docx, pptx]'

Requirements: Python 3.10 or higher

Key Features

• Structure Preservation: Maintains headings, lists, tables, links
• Plugin System: Extend with custom converters
• Docker Support: Containerized deployments
• MCP Integration: Model Context Protocol server for LLM apps

When to Read Supporting Files

• reference.md - Read when you need:

  • Complete API reference and all configuration options
  • Azure Document Intelligence integration details
  • Plugin development guide
  • Docker and MCP server setup
  • Troubleshooting and error handling

• examples.md - Read when you need:

  • Working examples for specific file types
  • Batch processing workflows
  • Error handling patterns
  • Integration with existing pipelines

• patterns.md - Read when you need:

  • Production deployment patterns
  • Performance optimization strategies
  • Security considerations
  • Anti-patterns to avoid

Quick Reference

File Type	Use Case	Command
PDF	Reports, papers	md.convert("file.pdf")
Word	Documents	md.convert("file.docx")
Excel	Data tables	md.convert("file.xlsx")
PowerPoint	Presentations	md.convert("file.pptx")
Images	Diagrams with OCR	md = MarkItDown(llm_client=client); md.convert("img.jpg")
HTML	Web pages	md.convert("page.html")
ZIP	Archives	md.convert("archive.zip") - processes contents

⚠️ Common Mistakes to Avoid

Anti-Pattern 1: Hardcoded API Keys

# ❌ NEVER DO THIS
md = MarkItDown(llm_client=OpenAI(api_key="sk-hardcoded-key"))

# ✅ ALWAYS DO THIS
api_key = os.getenv("OPENAI_API_KEY")
md = MarkItDown(llm_client=OpenAI(api_key=api_key))

Anti-Pattern 2: Unvalidated File Paths

# ❌ Vulnerable to path traversal
user_input = "../../../etc/passwd"
md.convert(user_input)

# ✅ Validate and sanitize
from pathlib import Path
safe_path = Path(user_input).resolve()
if not safe_path.is_relative_to(allowed_dir):
    raise ValueError("Invalid path")
md.convert(str(safe_path))

Anti-Pattern 3: Ignoring File Size Limits

# ❌ Can cause DoS
md.convert("huge_file.pdf")  # No size check

# ✅ Check size first
max_size = 50 * 1024 * 1024  # 50MB
if Path("file.pdf").stat().st_size > max_size:
    raise ValueError("File too large")

Common Issues

Import Error: Ensure Python >= 3.10 and markitdown installed Missing Dependencies: Install with pip install 'markitdown[all]' Image Descriptions Not Working: Requires LLM client (OpenAI or compatible)

For detailed troubleshooting, see reference.md.