Markitdown

MarkItDown Skill

Microsoft's Python utility for converting various file formats to Markdown for LLM and text analysis pipelines.

Overview

MarkItDown converts documents while preserving structure (headings, lists, tables, links). It's optimized for LLM consumption rather than human-readable output.

Supported Formats

Quick Start

Installation

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

# Minimal with specific formats
pip install 'markitdown[pdf,docx,pptx]'

# Using uv
uv pip install 'markitdown[all]'

Optional Dependencies

Command-Line Usage

# Basic conversion
markitdown document.pdf > output.md

# Specify output file
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown > output.md

# With Azure Document Intelligence
markitdown document.pdf -o output.md -d -e "<endpoint>"

Python API

from markitdown import MarkItDown

# Basic conversion
md = MarkItDown()
result = md.convert("document.xlsx")
print(result.text_content)

# With LLM for image descriptions
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail"
)
result = md.convert("image.jpg")
print(result.text_content)

# With Azure Document Intelligence
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("complex-document.pdf")
print(result.text_content)

Common Use Cases

Batch Convert Directory

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
input_dir = Path("./documents")
output_dir = Path("./markdown")
output_dir.mkdir(exist_ok=True)

for file in input_dir.glob("*"):
    if file.is_file():
        try:
            result = md.convert(str(file))
            output_file = output_dir / f"{file.stem}.md"
            output_file.write_text(result.text_content)
            print(f"Converted: {file.name}")
        except Exception as e:
            print(f"Failed: {file.name} - {e}")

Process for LLM Context

from markitdown import MarkItDown

def prepare_for_llm(file_path: str) -> str:
    """Convert document to LLM-ready markdown."""
    md = MarkItDown()
    result = md.convert(file_path)

    # Add source reference
    content = f"# Source: {file_path}\n\n{result.text_content}"
    return content

# Use with your LLM
context = prepare_for_llm("report.pdf")

Extract YouTube Transcript

# CLI
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" > transcript.md

# Python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Image OCR with AI Description

from markitdown import MarkItDown
from openai import OpenAI

# Initialize with LLM support
client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

# Convert image with AI description
result = md.convert("screenshot.png")
print(result.text_content)

Convert Jupyter Notebook

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("analysis.ipynb")
print(result.text_content)  # Code cells, outputs, markdown

Extract Wikipedia Content

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content)  # Main article content only

Parse RSS Feed

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://example.com/feed.xml")
print(result.text_content)  # Feed entries as markdown

Plugin System

MarkItDown supports third-party plugins for extended functionality.

# List installed plugins
markitdown --list-plugins

# Enable plugins during conversion
markitdown --use-plugins document.pdf

# Enable plugins in Python
md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")

Search GitHub for #markitdown-plugin to find available plugins.

MCP Server Integration

MarkItDown offers an MCP (Model Context Protocol) server for integration with LLM applications like Claude Desktop.

# Install MCP server
pip install markitdown-mcp

# Or from source
git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
pip install -e .

See [markitdown-mcp][mcp-repo] for configuration details.

[mcp-repo]: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp

Docker Usage

# Build image
docker build -t markitdown:latest .

# Convert file
docker run --rm -i markitdown:latest < document.pdf > output.md

Troubleshooting

Common Errors

# ModuleNotFoundError for specific format
pip install 'markitdown[pdf]'  # Install missing dependency

# Azure authentication
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="<endpoint>"
export AZURE_DOCUMENT_INTELLIGENCE_KEY="<key>"

Requirements

• Python >= 3.10
• Virtual environment recommended

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install
pip install 'markitdown[all]'

References

• references/cli-reference.md - Complete CLI options
• references/api-reference.md - Python API details
• references/examples.md - Extended examples
• references/advanced-features.md - Custom converters, URI handling
• GitHub: <https://github.com/microsoft/markitdown>
• PyPI: <https://pypi.org/project/markitdown/>

---

Gotchas

• DOCX with embedded images: images extract to separate files; markdown uses absolute paths — moving the markdown file alone breaks the image refs.
• PDF OCR confidence isn't surfaced — low-confidence text is returned as if certain; downstream LLM use can be confidently wrong.
• XLSX merged cells extract as separate cells with empty values for non-anchor positions — pivoted reports lose their column groupings invisibly.
• HTML to markdown loses CSS-driven layout — column-positioned tables collapse to row-major linear output; complex tables become unparseable.
• The `--use-llm` flag for image descriptions silently falls back to filename if no OPENAI_API_KEY — outputs look populated but contain no real description.

MarkItDown Advanced Features

Advanced functionality for custom converters, URI handling, and plugins.

Conversion Methods

MarkItDown provides multiple conversion entry points.

convert()

Universal method that auto-detects source type.

from markitdown import MarkItDown

md = MarkItDown()

# File path
result = md.convert("document.pdf")

# URL
result = md.convert("https://example.com/page.html")

# HTTP Response object
import requests
response = requests.get("https://example.com/doc.pdf")
result = md.convert(response)

convert_local()

For local file paths only.

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert_local("./documents/report.pdf")
print(result.text_content)

convert_stream()

For binary file-like objects.

from markitdown import MarkItDown
import io

md = MarkItDown()

# From bytes
with open("document.pdf", "rb") as f:
    content = f.read()

stream = io.BytesIO(content)
result = md.convert_stream(stream)

# From HTTP response
import requests
response = requests.get("https://example.com/doc.pdf")
stream = io.BytesIO(response.content)
result = md.convert_stream(stream)

Note: convert_stream() requires binary streams only (v0.1.0+).

Text streams (io.StringIO) are not supported.

convert_url()

For HTTP/HTTPS URLs.

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert_url("https://example.com/document.pdf")
print(result.text_content)

convert_uri()

For any URI scheme (http, https, file, data).

from markitdown import MarkItDown

md = MarkItDown()

# HTTP URL
result = md.convert_uri("https://example.com/page.html")

# Local file URI
result = md.convert_uri("file:///path/to/document.pdf")

# Data URI
result = md.convert_uri("data:text/plain;base64,SGVsbG8gV29ybGQ=")

convert_response()

For requests.Response objects.

from markitdown import MarkItDown
import requests

md = MarkItDown()
response = requests.get("https://example.com/report.pdf")
result = md.convert_response(response)
print(result.text_content)

Result Object

The DocumentConverterResult contains conversion output.

from markitdown import MarkItDown

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

# Main content
print(result.text_content)

# Alias for text_content
print(result.markdown)

# Document title (if available)
if result.title:
    print(f"Title: {result.title}")

Custom Converters

Create custom converters for unsupported formats.

Basic Custom Converter

from markitdown import MarkItDown
from markitdown._base_converter import DocumentConverter
from markitdown._base_converter import DocumentConverterResult
from typing import BinaryIO

class MyFormatConverter(DocumentConverter):
    """Converter for .myformat files."""

    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: "StreamInfo",
        **kwargs
    ) -> bool:
        """Check if this converter handles the file."""
        # Check by extension
        if stream_info.extension:
            return stream_info.extension.lower() == ".myformat"
        # Check by MIME type
        if stream_info.mime_type:
            return stream_info.mime_type == "application/x-myformat"
        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: "StreamInfo",
        **kwargs
    ) -> DocumentConverterResult:
        """Convert the file to markdown."""
        content = file_stream.read().decode("utf-8")

        # Process content...
        markdown = f"# My Format\n\n{content}"

        return DocumentConverterResult(
            title="My Document",
            text_content=markdown
        )

# Register the converter
md = MarkItDown()
md.register_converter(MyFormatConverter())

# Use it
result = md.convert("document.myformat")

Converter Priority

Converters are matched in priority order (lower = higher priority).

from markitdown import MarkItDown

md = MarkItDown()

# Register with high priority (runs first)
md.register_converter(MyConverter(), priority=10)

# Register with default priority
md.register_converter(AnotherConverter())  # Default priority

# Register with low priority (fallback)
md.register_converter(FallbackConverter(), priority=100)

Plugin Development

Create distributable plugins for MarkItDown.

Plugin Structure

markitdown-my-plugin/
  src/
    markitdown_my_plugin/
      __init__.py
      __about__.py
      _plugin.py
  pyproject.toml

Plugin Entry Point

# _plugin.py
from markitdown import MarkItDown
from ._converter import MyConverter

def register_converters(markitdown: MarkItDown, **kwargs):
    """Called when MarkItDown is instantiated with plugins."""
    markitdown.register_converter(MyConverter())

pyproject.toml

[project]
name = "markitdown-my-plugin"
version = "0.1.0"
dependencies = ["markitdown>=0.1.0"]

[project.entry-points."markitdown.plugin"]
my_plugin = "markitdown_my_plugin._plugin:register_converters"

Using Plugins

from markitdown import MarkItDown

# Enable all installed plugins
md = MarkItDown(enable_plugins=True)
result = md.convert("document.myformat")

# CLI: List installed plugins
markitdown --list-plugins

# CLI: Enable plugins
markitdown --use-plugins document.myformat

Built-in Converters Reference

MCP Server

MarkItDown provides an MCP server for LLM integration.

Installation

pip install markitdown-mcp

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

MCP Tool

The MCP server exposes a single tool:

convert_to_markdown(uri: str) -> str

Accepts http:, https:, file:, or data: URIs.

MarkItDown Python API Reference

Complete Python API documentation for MarkItDown.

Installation

pip install 'markitdown[all]'

Core Classes

MarkItDown

Main class for document conversion.

from markitdown import MarkItDown

md = MarkItDown(
    enable_plugins: bool = False,
    llm_client: Any = None,
    llm_model: str = None,
    llm_prompt: str = None,
    docintel_endpoint: str = None
)

Constructor Parameters

Methods

convert()

Convert a file or URL to Markdown.

result = md.convert(
    source: str | Path,
    **kwargs
) -> DocumentConverterResult

Returns: DocumentConverterResult

convert_stream()

Convert from a binary file-like object.

result = md.convert_stream(
    stream: BinaryIO,
    **kwargs
) -> DocumentConverterResult

Note: As of v0.1.0, convert_stream() requires binary streams only.

Text streams (io.StringIO) are no longer supported.

DocumentConverterResult

Result object from conversion.

@dataclass
class DocumentConverterResult:
    text_content: str  # The converted Markdown content
    title: str | None  # Document title if available

Basic Usage

Simple Conversion

from markitdown import MarkItDown

md = MarkItDown()

# Convert file
result = md.convert("document.pdf")
print(result.text_content)

# Access title if available
if result.title:
    print(f"Title: {result.title}")

Convert from Stream

from markitdown import MarkItDown
import io

md = MarkItDown()

# From bytes
with open("document.pdf", "rb") as f:
    content = f.read()

stream = io.BytesIO(content)
result = md.convert_stream(stream)
print(result.text_content)

# From HTTP response
import requests

response = requests.get("https://example.com/document.pdf")
stream = io.BytesIO(response.content)
result = md.convert_stream(stream)

Convert URL

from markitdown import MarkItDown

md = MarkItDown()

# YouTube video
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

# Web page
result = md.convert("https://example.com/article.html")
print(result.text_content)

Advanced Usage

LLM Image Descriptions

Use OpenAI or compatible API for intelligent image descriptions.

from markitdown import MarkItDown
from openai import OpenAI

# Initialize OpenAI client
client = OpenAI()  # Uses OPENAI_API_KEY env var

# Create MarkItDown with LLM support
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail, including any text visible."
)

# Convert image with AI description
result = md.convert("screenshot.png")
print(result.text_content)

# Convert PowerPoint with AI-described images
result = md.convert("presentation.pptx")
print(result.text_content)

Azure Document Intelligence

For complex PDFs with tables, forms, and scanned content.

from markitdown import MarkItDown

# Using endpoint directly
md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/"
)

result = md.convert("complex-form.pdf")
print(result.text_content)

# With environment variables
import os

os.environ["AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT"] = "https://..."
os.environ["AZURE_DOCUMENT_INTELLIGENCE_KEY"] = "your-key"

md = MarkItDown(docintel_endpoint=os.environ["AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT"])
result = md.convert("scanned-document.pdf")

Plugin System

from markitdown import MarkItDown

# Enable all installed plugins
md = MarkItDown(enable_plugins=True)

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

Batch Processing

Process Directory

from markitdown import MarkItDown
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor, as_completed

def convert_file(
    md: MarkItDown, file_path: Path, output_dir: Path
) -> tuple[Path, bool, str]:
    """Convert a single file and return status."""
    try:
        result = md.convert(str(file_path))
        output_file = output_dir / f"{file_path.stem}.md"
        output_file.write_text(result.text_content)
        return file_path, True, ""
    except Exception as e:
        return file_path, False, str(e)

def batch_convert(
    input_dir: str,
    output_dir: str,
    extensions: list[str] = None,
    max_workers: int = 4
) -> dict:
    """Convert all files in directory."""
    input_path = Path(input_dir)
    output_path = Path(output_dir)
    output_path.mkdir(parents=True, exist_ok=True)

    md = MarkItDown()
    results = {"success": [], "failed": []}

    # Collect files
    if extensions:
        files = []
        for ext in extensions:
            files.extend(input_path.glob(f"*.{ext}"))
    else:
        files = [f for f in input_path.iterdir() if f.is_file()]

    # Process in parallel
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {
            executor.submit(convert_file, md, f, output_path): f
            for f in files
        }

        for future in as_completed(futures):
            file_path, success, error = future.result()
            if success:
                results["success"].append(str(file_path))
            else:
                results["failed"].append({"file": str(file_path), "error": error})

    return results

# Usage
results = batch_convert(
    input_dir="./documents",
    output_dir="./markdown",
    extensions=["pdf", "docx", "pptx"],
    max_workers=4
)
print(f"Converted: {len(results['success'])}")
print(f"Failed: {len(results['failed'])}")

Process with Progress

from markitdown import MarkItDown
from pathlib import Path
from tqdm import tqdm

def convert_with_progress(input_dir: str, output_dir: str):
    """Convert files with progress bar."""
    input_path = Path(input_dir)
    output_path = Path(output_dir)
    output_path.mkdir(parents=True, exist_ok=True)

    md = MarkItDown()
    files = list(input_path.glob("*"))

    for file in tqdm(files, desc="Converting"):
        if file.is_file():
            try:
                result = md.convert(str(file))
                output_file = output_path / f"{file.stem}.md"
                output_file.write_text(result.text_content)
            except Exception as e:
                tqdm.write(f"Error: {file.name} - {e}")

# Usage
convert_with_progress("./documents", "./markdown")

Error Handling

from markitdown import MarkItDown

md = MarkItDown()

try:
    result = md.convert("document.pdf")
    print(result.text_content)
except FileNotFoundError:
    print("File not found")
except ValueError as e:
    print(f"Conversion error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Safe Conversion Function

from markitdown import MarkItDown
from typing import Optional

def safe_convert(file_path: str) -> Optional[str]:
    """Safely convert file, returning None on error."""
    md = MarkItDown()
    try:
        result = md.convert(file_path)
        return result.text_content
    except Exception:
        return None

# Usage
content = safe_convert("document.pdf")
if content:
    print(content)
else:
    print("Conversion failed")

Integration Examples

FastAPI Endpoint

from fastapi import FastAPI, UploadFile, HTTPException
from markitdown import MarkItDown
import io

app = FastAPI()
md = MarkItDown()

@app.post("/convert")
async def convert_document(file: UploadFile):
    """Convert uploaded document to Markdown."""
    try:
        content = await file.read()
        stream = io.BytesIO(content)
        result = md.convert_stream(stream)
        return {"markdown": result.text_content, "title": result.title}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

LangChain Document Loader

from markitdown import MarkItDown
from langchain.schema import Document

def load_document(file_path: str) -> Document:
    """Load document as LangChain Document."""
    md = MarkItDown()
    result = md.convert(file_path)

    return Document(
        page_content=result.text_content,
        metadata={
            "source": file_path,
            "title": result.title or ""
        }
    )

# Usage
doc = load_document("report.pdf")
print(doc.page_content[:500])

Type Hints

from markitdown import MarkItDown, DocumentConverterResult
from pathlib import Path
from typing import BinaryIO

def convert_file(path: str | Path) -> DocumentConverterResult:
    md = MarkItDown()
    return md.convert(str(path))

def convert_stream(stream: BinaryIO) -> str:
    md = MarkItDown()
    result = md.convert_stream(stream)
    return result.text_content

MarkItDown CLI Reference

Complete command-line interface documentation for MarkItDown.

Basic Syntax

markitdown [OPTIONS] [INPUT_FILE]

Arguments

Options

Usage Examples

Basic Conversion

# Convert PDF to markdown (stdout)
markitdown document.pdf

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

# Convert Word document
markitdown report.docx -o report.md

# Convert PowerPoint
markitdown presentation.pptx -o slides.md

# Convert Excel
markitdown data.xlsx -o data.md

Piping Input

# Pipe file content
cat document.pdf | markitdown > output.md

# Download and convert
curl -s "https://example.com/doc.pdf" | markitdown > output.md

# From clipboard (macOS)
pbpaste | markitdown

Batch Processing

# Convert all PDFs in directory
for f in *.pdf; do
    markitdown "$f" -o "${f%.pdf}.md"
done

# Using find for recursive conversion
find . -name "*.docx" -exec sh -c 'markitdown "$1" -o "${1%.docx}.md"' _ {} \;

# Parallel processing with xargs
ls *.pdf | xargs -P 4 -I {} sh -c 'markitdown "$1" -o "${1%.pdf}.md"' _ {}

URL Conversion

# YouTube video transcript
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o transcript.md

# Web page
markitdown "https://example.com/article" -o article.md

Azure Document Intelligence

# Set environment variables
ENDPOINT="https://your-resource.cognitiveservices.azure.com/"
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="$ENDPOINT"
export AZURE_DOCUMENT_INTELLIGENCE_KEY="your-key"

# Convert with Document Intelligence
markitdown complex-document.pdf -d \
  -e "$AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT" \
  -o output.md

# For better PDF extraction
markitdown scanned-document.pdf -d \
  -e "$AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT"

Plugin Usage

# List available plugins
markitdown --list-plugins

# Convert with plugins enabled
markitdown --use-plugins document.pdf -o output.md

# Check if specific plugin is installed
markitdown --list-plugins | grep "plugin-name"

Exit Codes

Environment Variables

File Format Detection

MarkItDown automatically detects file formats based on:

1. File extension 2. MIME type 3. File magic bytes

Supported extensions:

Tips and Best Practices

Performance

# For large files, redirect to file instead of stdout
markitdown large-file.pdf -o output.md  # Faster than > output.md

# Process multiple files in parallel
parallel markitdown {} -o {.}.md ::: *.pdf

Error Handling

# Check if conversion succeeded
if markitdown document.pdf -o output.md; then
    echo "Conversion successful"
else
    echo "Conversion failed" >&2
fi

# Capture errors
markitdown document.pdf -o output.md 2>errors.log

Integration with Other Tools

# Convert and search
markitdown document.pdf | grep -i "keyword"

# Convert and count words
markitdown document.pdf | wc -w

# Convert and extract links
markitdown document.pdf | grep -oE '\[.*?\]\(.*?\)'

# Convert and send to LLM
markitdown document.pdf | llm "Summarize this document"

MarkItDown Examples

Practical examples for common use cases.

Document Processing

Extract Text from PDF

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.pdf")

# Get plain text
text = result.text_content
print(f"Extracted {len(text)} characters")

Convert Word Document

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.docx")

# Save as markdown file
with open("document.md", "w") as f:
    f.write(result.text_content)

Process PowerPoint Presentation

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("slides.pptx")

# Each slide becomes a section
print(result.text_content)

Extract Data from Excel

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xlsx")

# Tables are converted to Markdown tables
print(result.text_content)

Image Processing

Basic OCR

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("screenshot.png")

# Extracts EXIF metadata and OCR text
print(result.text_content)

AI-Powered Image Description

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail."
)

result = md.convert("diagram.png")
print(result.text_content)

Process Multiple Images

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
image_dir = Path("./images")

for image in image_dir.glob("*.png"):
    result = md.convert(str(image))
    output = image_dir / f"{image.stem}.md"
    output.write_text(f"# {image.name}\n\n{result.text_content}")
    print(f"Processed: {image.name}")

Audio Processing

Transcribe Audio File

from markitdown import MarkItDown

# Requires [audio-transcription] extra
md = MarkItDown()
result = md.convert("interview.mp3")

print(result.text_content)

Process Meeting Recording

from markitdown import MarkItDown
from datetime import datetime

md = MarkItDown()
result = md.convert("meeting.wav")

# Add metadata
output = f"""# Meeting Transcript
Date: {datetime.now().strftime("%Y-%m-%d")}

## Transcript

{result.text_content}
"""

with open("meeting-notes.md", "w") as f:
    f.write(output)

Web Content

YouTube Video Transcript

from markitdown import MarkItDown

# Requires [youtube-transcription] extra
md = MarkItDown()
result = md.convert("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

print(result.text_content)

Extract YouTube Video for Notes

from markitdown import MarkItDown

def youtube_to_notes(video_url: str, output_path: str):
    """Convert YouTube video to study notes."""
    md = MarkItDown()
    result = md.convert(video_url)

    # Structure the output
    content = f"""# Video Notes

Source: {video_url}

## Transcript

{result.text_content}

## Key Points

[Add your notes here]

## Questions

[Add questions for review]
"""

    with open(output_path, "w") as f:
        f.write(content)

# Usage
youtube_to_notes(
    "https://www.youtube.com/watch?v=VIDEO_ID",
    "lecture-notes.md"
)

Convert HTML Page

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("page.html")

# Preserves structure: headings, lists, links
print(result.text_content)

Data Files

CSV to Markdown Table

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.csv")

# Data becomes a Markdown table
print(result.text_content)

JSON to Markdown

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("config.json")

print(result.text_content)

XML to Markdown

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xml")

print(result.text_content)

Archive Processing

Process ZIP Contents

from markitdown import MarkItDown

md = MarkItDown()

# Iterates through ZIP contents
result = md.convert("documents.zip")
print(result.text_content)

Extract Documentation from ZIP

from markitdown import MarkItDown
from pathlib import Path
import zipfile
import tempfile

def extract_docs_from_zip(zip_path: str) -> str:
    """Extract and convert all documents from ZIP."""
    md = MarkItDown()
    all_content = []

    with tempfile.TemporaryDirectory() as temp_dir:
        with zipfile.ZipFile(zip_path, 'r') as zf:
            zf.extractall(temp_dir)

        for file in Path(temp_dir).rglob("*"):
            if file.is_file() and file.suffix in ['.pdf', '.docx', '.txt']:
                try:
                    result = md.convert(str(file))
                    all_content.append(f"## {file.name}\n\n{result.text_content}")
                except Exception as e:
                    all_content.append(f"## {file.name}\n\nError: {e}")

    return "\n\n---\n\n".join(all_content)

# Usage
content = extract_docs_from_zip("project-docs.zip")
with open("all-docs.md", "w") as f:
    f.write(content)

LLM Integration

Prepare Documents for RAG

from markitdown import MarkItDown
from pathlib import Path

def prepare_for_rag(docs_dir: str) -> list[dict]:
    """Prepare documents for RAG indexing."""
    md = MarkItDown()
    documents = []

    for file in Path(docs_dir).glob("*"):
        if file.is_file():
            try:
                result = md.convert(str(file))
                documents.append({
                    "source": str(file),
                    "title": result.title or file.stem,
                    "content": result.text_content
                })
            except Exception as e:
                print(f"Skipped {file}: {e}")

    return documents

# Usage
docs = prepare_for_rag("./knowledge-base")
print(f"Prepared {len(docs)} documents")

Summarize Document with LLM

from markitdown import MarkItDown
from openai import OpenAI

def summarize_document(file_path: str) -> str:
    """Convert document and generate summary."""
    # Convert to markdown
    md = MarkItDown()
    result = md.convert(file_path)

    # Summarize with LLM
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Summarize the following document concisely."},
            {"role": "user", "content": result.text_content[:10000]}
        ]
    )

    return response.choices[0].message.content

# Usage
summary = summarize_document("long-report.pdf")
print(summary)

Q&A Over Documents

from markitdown import MarkItDown
from openai import OpenAI

class DocumentQA:
    def __init__(self):
        self.md = MarkItDown()
        self.client = OpenAI()
        self.documents = {}

    def load_document(self, file_path: str, doc_id: str):
        """Load and convert document."""
        result = self.md.convert(file_path)
        self.documents[doc_id] = result.text_content

    def ask(self, doc_id: str, question: str) -> str:
        """Ask question about loaded document."""
        if doc_id not in self.documents:
            raise ValueError(f"Document {doc_id} not loaded")

        response = self.client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {
                    "role": "system",
                    "content": f"Answer questions based on this document:\n\n{self.documents[doc_id][:15000]}"
                },
                {"role": "user", "content": question}
            ]
        )

        return response.choices[0].message.content

# Usage
qa = DocumentQA()
qa.load_document("contract.pdf", "contract")
answer = qa.ask("contract", "What are the payment terms?")
print(answer)

Jupyter Notebooks

Convert Notebook to Markdown

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("analysis.ipynb")

# Output includes code cells, outputs, and markdown cells
print(result.text_content)

Extract Code from Notebook

from markitdown import MarkItDown
import re

def extract_code_cells(notebook_path: str) -> list[str]:
    """Extract only code from notebook."""
    md = MarkItDown()
    result = md.convert(notebook_path)

    # Find code blocks
    code_blocks = re.findall(
        r"```python\n(.*?)```",
        result.text_content,
        re.DOTALL
    )
    return code_blocks

# Usage
code = extract_code_cells("data_analysis.ipynb")
for i, block in enumerate(code, 1):
    print(f"--- Cell {i} ---")
    print(block)

Batch Convert Notebooks

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

for notebook in Path("./notebooks").glob("*.ipynb"):
    result = md.convert(str(notebook))
    output = notebook.with_suffix(".md")
    output.write_text(result.text_content)
    print(f"Converted: {notebook.name}")

RSS and Atom Feeds

Parse RSS Feed

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://example.com/feed.rss")

# Feed entries converted to markdown
print(result.text_content)

Monitor Multiple Feeds

from markitdown import MarkItDown
from datetime import datetime

def aggregate_feeds(feed_urls: list[str]) -> str:
    """Combine multiple RSS feeds into one document."""
    md = MarkItDown()
    sections = []

    for url in feed_urls:
        try:
            result = md.convert(url)
            sections.append(f"## Feed: {url}\n\n{result.text_content}")
        except Exception as e:
            sections.append(f"## Feed: {url}\n\nError: {e}")

    header = f"# Feed Aggregation\nGenerated: {datetime.now()}\n\n"
    return header + "\n\n---\n\n".join(sections)

# Usage
feeds = [
    "https://news.ycombinator.com/rss",
    "https://example.com/blog/feed.xml"
]
content = aggregate_feeds(feeds)
print(content)

Wikipedia

Extract Article Content

from markitdown import MarkItDown

md = MarkItDown()

# Extracts main article content, excludes navigation/sidebars
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content)

Research Multiple Topics

from markitdown import MarkItDown
from pathlib import Path

def research_topics(topics: list[str], output_dir: str):
    """Download Wikipedia articles for research."""
    md = MarkItDown()
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    for topic in topics:
        url = f"https://en.wikipedia.org/wiki/{topic.replace(' ', '_')}"
        try:
            result = md.convert(url)
            filename = f"{topic.lower().replace(' ', '-')}.md"
            (output_path / filename).write_text(result.text_content)
            print(f"Downloaded: {topic}")
        except Exception as e:
            print(f"Failed: {topic} - {e}")

# Usage
research_topics(
    ["Machine learning", "Neural network", "Deep learning"],
    "./research"
)

Build Knowledge Base from Wikipedia

from markitdown import MarkItDown

def build_wiki_context(topics: list[str]) -> str:
    """Build LLM context from Wikipedia articles."""
    md = MarkItDown()
    sections = []

    for topic in topics:
        url = f"https://en.wikipedia.org/wiki/{topic.replace(' ', '_')}"
        try:
            result = md.convert(url)
            # Truncate long articles
            content = result.text_content[:5000]
            sections.append(f"## {topic}\n\n{content}")
        except Exception:
            continue

    return "\n\n---\n\n".join(sections)

# Usage
context = build_wiki_context(["Python", "JavaScript", "Rust"])

Azure Document Intelligence

Complex PDF with Tables

from markitdown import MarkItDown
import os

# Set up credentials
os.environ["AZURE_DOCUMENT_INTELLIGENCE_KEY"] = "your-key"

md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/"
)

# Better extraction for complex layouts
result = md.convert("financial-report.pdf")
print(result.text_content)

Scanned Document Processing

from markitdown import MarkItDown

md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/"
)

# OCR and layout analysis for scanned docs
result = md.convert("scanned-contract.pdf")
print(result.text_content)

CLI Examples

Basic Conversion

# PDF to stdout
markitdown report.pdf

# Save to file
markitdown report.pdf -o report.md

# Word document
markitdown document.docx -o document.md

# PowerPoint
markitdown slides.pptx -o slides.md

Batch Processing

# Convert all PDFs
for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done

# With parallel processing
ls *.pdf | xargs -P 4 -I {} sh -c 'markitdown "$1" -o "${1%.pdf}.md"' _ {}

# Recursive conversion
find . -name "*.docx" -exec sh -c 'markitdown "$1" -o "${1%.docx}.md"' _ {} \;

Piping and Integration

# Pipe to grep
markitdown document.pdf | grep -i "important"

# Count words
markitdown document.pdf | wc -w

# Send to LLM CLI
markitdown document.pdf | llm "Summarize this document"

# Download and convert
curl -sL "https://example.com/doc.pdf" | markitdown > doc.md

Document Intelligence CLI

# Set credentials
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="https://..."
export AZURE_DOCUMENT_INTELLIGENCE_KEY="..."

# Convert with Document Intelligence
markitdown complex.pdf -d -e "$AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT" -o output.md