Document to Markdown Conversion Skill

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.

Agent Skills: Document to Markdown Conversion

Install this agent skill to your local

Skill Files