markitdown

# MarkItDown - File to Markdown Conversion

## Overview

MarkItDown is a Python tool developed by Microsoft for converting various file formats to Markdown. It's particularly useful for converting documents into LLM-friendly text format, as Markdown is token-efficient and well-understood by modern language models.

**Key Benefits**:
- Convert documents to clean, structured Markdown
- Token-efficient format for LLM processing
- Supports 15+ file formats
- Optional AI-enhanced image descriptions
- OCR for images and scanned documents
- Speech transcription for audio files

## Visual Enhancement with Scientific Schematics

**When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**

If your document does not already contain schematics or diagrams:
- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
- Simply describe your desired diagram in natural language
- Nano Banana Pro will automatically generate, review, and refine the schematic

**For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.

**How to generate schematics:**
```bash
python scripts/generate_schematic.py "your diagram description" -o figures/output.png
```

The AI will automatically:
- Create publication-quality images with proper formatting
- Review and refine through multiple iterations
- Ensure accessibility (colorblind-friendly, high contrast)
- Save outputs in the figures/ directory

**When to add schematics:**
- Document conversion workflow diagrams
- File format architecture illustrations
- OCR processing pipeline diagrams
- Integration workflow visualizations
- System architecture diagrams
- Data flow diagrams
- Any complex concept that benefits from visualization

For detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.

---

## Supported Formats

| Format | Description | Notes |
|--------|-------------|-------|
| **PDF** | Portable Document Format | Full text extraction |
| **DOCX** | Microsoft Word | Tables, formatting preserved |
| **PPTX** | PowerPoint | Slides with notes |
| **XLSX** | Excel spreadsheets | Tables and data |
| **Images** | JPEG, PNG, GIF, WebP | EXIF metadata + OCR |
| **Audio** | WAV, MP3 | Metadata + transcription |
| **HTML** | Web pages | Clean conversion |
| **CSV** | Comma-separated values | Table format |
| **JSON** | JSON data | Structured representation |
| **XML** | XML documents | Structured format |
| **ZIP** | Archive files | Iterates contents |
| **EPUB** | E-books | Full text extraction |
| **YouTube** | Video URLs | Fetch transcriptions |

## Quick Start

### Installation

```bash
# Install with all features
pip install 'markitdown[all]'

# Or from source
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
```

### Command-Line Usage

```bash
# Basic conversion
markitdown document.pdf > output.md

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

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

# Enable plugins
markitdown --list-plugins  # List available plugins
markitdown --use-plugins document.pdf -o output.md
```

### Python API

```python
from markitdown import MarkItDown

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

# Convert from stream
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)
```

## Advanced Features

### 1. AI-Enhanced Image Descriptions

Use LLMs via OpenRouter to generate detailed image descriptions (for PPTX and image files):

```python
from markitdown import MarkItDown
from openai import OpenAI

# Initialize OpenRouter client (OpenAI-compatible API)
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",  # recommended for scientific vision
    llm_prompt="Describe this image in detail for scientific documentation"
)

result = md.convert("presentation.pptx")
print(result.text_content)
```

### 2. Azure Document Intelligence

For enhanced PDF conversion with Microsoft Document Intelligence:

```bash
# Command line
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"
```

```python
# Python API
from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("complex_document.pdf")
print(result.text_content)
```

### 3. Plugin System

MarkItDown supports 3rd-party plugins for extending functionality:

```bash
# List installed plugins
markitdown --list-plugins

# Enable plugins
markitdown --use-plugins file.pdf -o output.md
```

Find plugins on GitHub with hashtag: `#markitdown-plugin`

## Optional Dependencies

Control which file formats you support:

```bash
# Install specific formats
pip install 'markitdown[pdf, docx, pptx]'

# All available options:
# [all]                  - All optional dependencies
# [pptx]                 - PowerPoint files
# [docx]                 - Word documents
# [xlsx]                 - Excel spreadsheets
# [xls]                  - Older Excel files
# [pdf]                  - PDF documents
# [outlook]              - Outlook messages
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAV and MP3 transcription
# [youtube-transcription] - YouTube video transcription
```

## Common Use Cases

### 1. Convert Scientific Papers to Markdown

```python
from markitdown import MarkItDown

md = MarkItDown()

# Convert PDF paper
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
    f.write(result.text_content)
```

### 2. Extract Data from Excel for Analysis

```python
from markitdown import MarkItDown

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

# Result will be in Markdown table format
print(result.text_content)
```

### 3. Process Multiple Documents

```python
from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# Process all PDFs in a directory
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_file = output_dir / f"{pdf_file.stem}.md"
    output_file.write_text(result.text_content)
    print(f"Converted: {pdf_file.name}")
```

### 4. Convert PowerPoint with AI Descriptions

```python
from markitdown import MarkItDown
from openai import OpenAI

# Use OpenRouter for access to multiple AI models
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",  # recommended for presentations
    llm_prompt="Describe this slide image in detail, focusing on key visual elements and data"
)

result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
    f.write(result.text_content)
```

### 5. Batch Convert with Different Formats

```python
from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Files to convert
files = [
    "document.pdf",
    "spreadsheet.xlsx",
    "presentation.pptx",
    "notes.docx"
]

for file in files:
    try:
        result = md.convert(file)
        output = Path(file).stem + ".md"
        with open(output, "w") as f:
            f.write(result.text_content)
        print(f"✓ Converted {file}")
    except Exception as e:
        print(f"✗ Error converting {file}: {e}")
```

### 6. Extract YouTube Video Transcription

```python
from markitdown import MarkItDown

md = MarkItDown()

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

## Docker Usage

```bash
# Build image
docker build -t markitdown:latest .

# Run conversion
docker run --rm -i markitdown:latest < ~/document.pdf > output.md
```

## Best Practices

### 1. Choose the Right Conversion Method

- **Simple documents**: Use basic `MarkItDown()`
- **Complex PDFs**: Use Azure Document Intelligence
- **Visual content**: Enable AI image descriptions
- **Scanned documents**: Ensure OCR dependencies are installed

### 2. Handle Errors Gracefully

```python
from markitdown import MarkItDown

md = MarkItDown()

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

### 3. Process Large Files Efficiently

```python
from markitdown import MarkItDown

md = MarkItDown()

# For large files, use streaming
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # Process in chunks or save directly
    with open("output.md", "w") as out:
        out.write(result.text_content)
```

### 4. Optimize for Token Efficiency

Markdown output is already token-efficient, but you can:
- Remove excessive whitespace
- Consolidate similar sections
- Strip metadata if not needed

```python
from markitdown import MarkItDown
import re

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

# Clean up extra whitespace
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()

print(clean_text)
```

## Integration with Scientific Workflows

### Convert Literature for Review

```python
from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Convert all papers in literature folder
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)

for paper in papers_dir.glob("*.pdf"):
    result = md.convert(str(paper))
    
    # Save with metadata
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**Source**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# For AI-enhanced conversion with figures
from openai import OpenAI

client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",
    llm_prompt="Describe scientific figures with technical precision"
)
```

### Extract Tables for Analysis

```python
from markitdown import MarkItDown
import re

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

# Markdown tables can be parsed or used directly
print(result.text_content)
```

## Troubleshooting

### Common Issues

1. **Missing dependencies**: Install feature-specific packages
   ```bash
   pip install 'markitdown[pdf]'  # For PDF support
   ```

2. **Binary file errors**: Ensure files are opened in binary mode
   ```python
   with open("file.pdf", "rb") as f:  # Note the "rb"
       result = md.convert_stream(f, file_extension=".pdf")
   ```

3. **OCR not working**: Install tesseract
   ```bash
   # macOS
   brew install tesseract
   
   # Ubuntu
   sudo apt-get install tesseract-ocr
   ```

## Performance Considerations

- **PDF files**: Large PDFs may take time; consider page ranges if supported
- **Image OCR**: OCR processing is CPU-intensive
- **Audio transcription**: Requires additional compute resources
- **AI image descriptions**: Requires API calls (costs may apply)

## Next Steps

- See `references/api_reference.md` for complete API documentation
- Check `references/file_formats.md` for format-specific details
- Review `scripts/batch_convert.py` for automation examples
- Explore `scripts/convert_with_ai.py` for AI-enhanced conversions

## Resources

- **MarkItDown GitHub**: https://github.com/microsoft/markitdown
- **PyPI**: https://pypi.org/project/markitdown/
- **OpenRouter**: https://openrouter.ai (for AI-enhanced conversions)
- **OpenRouter API Keys**: https://openrouter.ai/keys
- **OpenRouter Models**: https://openrouter.ai/models
- **MCP Server**: markitdown-mcp (for Claude Desktop integration)
- **Plugin Development**: See `packages/markitdown-sample-plugin`

{
  "format": "aiskill/v1",
  "skill": {
    "name": "markitdown",
    "slug": "markitdown",
    "version": "1.0.0",
    "description": "Convert files and office documents to Markdown. Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs and more.",
    "category": "Research",
    "tags": [
      "research-science",
      "documents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT LICENSE"
  },
  "prompts": {
    "system": "# MarkItDown - File to Markdown Conversion\r\n\r\n## Overview\r\n\r\nMarkItDown is a Python tool developed by Microsoft for converting various file formats to Markdown. It's particularly useful for converting documents into LLM-friendly text format, as Markdown is token-efficient and well-understood by modern language models.\r\n\r\n**Key Benefits**:\r\n- Convert documents to clean, structured Markdown\r\n- Token-efficient format for LLM processing\r\n- Supports 15+ file formats\r\n- Optional AI-enhanced image descriptions\r\n- OCR for images and scanned documents\r\n- Speech transcription for audio files\r\n\r\n## Visual Enhancement with Scientific Schematics\r\n\r\n**When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**\r\n\r\nIf your document does not already contain schematics or diagrams:\r\n- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams\r\n- Simply describe your desired diagram in natural language\r\n- Nano Banana Pro will automatically generate, review, and refine the schematic\r\n\r\n**For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.\r\n\r\n**How to generate schematics:**\r\n```bash\r\npython scripts/generate_schematic.py \"your diagram description\" -o figures/output.png\r\n```\r\n\r\nThe AI will automatically:\r\n- Create publication-quality images with proper formatting\r\n- Review and refine through multiple iterations\r\n- Ensure accessibility (colorblind-friendly, high contrast)\r\n- Save outputs in the figures/ directory\r\n\r\n**When to add schematics:**\r\n- Document conversion workflow diagrams\r\n- File format architecture illustrations\r\n- OCR processing pipeline diagrams\r\n- Integration workflow visualizations\r\n- System architecture diagrams\r\n- Data flow diagrams\r\n- Any complex concept that benefits from visualization\r\n\r\nFor detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.\r\n\r\n---\r\n\r\n## Supported Formats\r\n\r\n| Format | Description | Notes |\r\n|--------|-------------|-------|\r\n| **PDF** | Portable Document Format | Full text extraction |\r\n| **DOCX** | Microsoft Word | Tables, formatting preserved |\r\n| **PPTX** | PowerPoint | Slides with notes |\r\n| **XLSX** | Excel spreadsheets | Tables and data |\r\n| **Images** | JPEG, PNG, GIF, WebP | EXIF metadata + OCR |\r\n| **Audio** | WAV, MP3 | Metadata + transcription |\r\n| **HTML** | Web pages | Clean conversion |\r\n| **CSV** | Comma-separated values | Table format |\r\n| **JSON** | JSON data | Structured representation |\r\n| **XML** | XML documents | Structured format |\r\n| **ZIP** | Archive files | Iterates contents |\r\n| **EPUB** | E-books | Full text extraction |\r\n| **YouTube** | Video URLs | Fetch transcriptions |\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\n# Install with all features\r\npip install 'markitdown[all]'\r\n\r\n# Or from source\r\ngit clone https://github.com/microsoft/markitdown.git\r\ncd markitdown\r\npip install -e 'packages/markitdown[all]'\r\n```\r\n\r\n### Command-Line Usage\r\n\r\n```bash\r\n# Basic conversion\r\nmarkitdown document.pdf > output.md\r\n\r\n# Specify output file\r\nmarkitdown document.pdf -o output.md\r\n\r\n# Pipe content\r\ncat document.pdf | markitdown > output.md\r\n\r\n# Enable plugins\r\nmarkitdown --list-plugins  # List available plugins\r\nmarkitdown --use-plugins document.pdf -o output.md\r\n```\r\n\r\n### Python API\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\n# Basic usage\r\nmd = MarkItDown()\r\nresult = md.convert(\"document.pdf\")\r\nprint(result.text_content)\r\n\r\n# Convert from stream\r\nwith open(\"document.pdf\", \"rb\") as f:\r\n    result = md.convert_stream(f, file_extension=\".pdf\")\r\n    print(result.text_content)\r\n```\r\n\r\n## Advanced Features\r\n\r\n### 1. AI-Enhanced Image Descriptions\r\n\r\nUse LLMs via OpenRouter to generate detailed image descriptions (for PPTX and image files):\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom openai import OpenAI\r\n\r\n# Initialize OpenRouter client (OpenAI-compatible API)\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",  # recommended for scientific vision\r\n    llm_prompt=\"Describe this image in detail for scientific documentation\"\r\n)\r\n\r\nresult = md.convert(\"presentation.pptx\")\r\nprint(result.text_content)\r\n```\r\n\r\n### 2. Azure Document Intelligence\r\n\r\nFor enhanced PDF conversion with Microsoft Document Intelligence:\r\n\r\n```bash\r\n# Command line\r\nmarkitdown document.pdf -o output.md -d -e \"<document_intelligence_endpoint>\"\r\n```\r\n\r\n```python\r\n# Python API\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown(docintel_endpoint=\"<document_intelligence_endpoint>\")\r\nresult = md.convert(\"complex_document.pdf\")\r\nprint(result.text_content)\r\n```\r\n\r\n### 3. Plugin System\r\n\r\nMarkItDown supports 3rd-party plugins for extending functionality:\r\n\r\n```bash\r\n# List installed plugins\r\nmarkitdown --list-plugins\r\n\r\n# Enable plugins\r\nmarkitdown --use-plugins file.pdf -o output.md\r\n```\r\n\r\nFind plugins on GitHub with hashtag: `#markitdown-plugin`\r\n\r\n## Optional Dependencies\r\n\r\nControl which file formats you support:\r\n\r\n```bash\r\n# Install specific formats\r\npip install 'markitdown[pdf, docx, pptx]'\r\n\r\n# All available options:\r\n# [all]                  - All optional dependencies\r\n# [pptx]                 - PowerPoint files\r\n# [docx]                 - Word documents\r\n# [xlsx]                 - Excel spreadsheets\r\n# [xls]                  - Older Excel files\r\n# [pdf]                  - PDF documents\r\n# [outlook]              - Outlook messages\r\n# [az-doc-intel]         - Azure Document Intelligence\r\n# [audio-transcription]  - WAV and MP3 transcription\r\n# [youtube-transcription] - YouTube video transcription\r\n```\r\n\r\n## Common Use Cases\r\n\r\n### 1. Convert Scientific Papers to Markdown\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert PDF paper\r\nresult = md.convert(\"research_paper.pdf\")\r\nwith open(\"paper.md\", \"w\") as f:\r\n    f.write(result.text_content)\r\n```\r\n\r\n### 2. Extract Data from Excel for Analysis\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"data.xlsx\")\r\n\r\n# Result will be in Markdown table format\r\nprint(result.text_content)\r\n```\r\n\r\n### 3. Process Multiple Documents\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport os\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Process all PDFs in a directory\r\npdf_dir = Path(\"papers/\")\r\noutput_dir = Path(\"markdown_output/\")\r\noutput_dir.mkdir(exist_ok=True)\r\n\r\nfor pdf_file in pdf_dir.glob(\"*.pdf\"):\r\n    result = md.convert(str(pdf_file))\r\n    output_file = output_dir / f\"{pdf_file.stem}.md\"\r\n    output_file.write_text(result.text_content)\r\n    print(f\"Converted: {pdf_file.name}\")\r\n```\r\n\r\n### 4. Convert PowerPoint with AI Descriptions\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom openai import OpenAI\r\n\r\n# Use OpenRouter for access to multiple AI models\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",  # recommended for presentations\r\n    llm_prompt=\"Describe this slide image in detail, focusing on key visual elements and data\"\r\n)\r\n\r\nresult = md.convert(\"presentation.pptx\")\r\nwith open(\"presentation.md\", \"w\") as f:\r\n    f.write(result.text_content)\r\n```\r\n\r\n### 5. Batch Convert with Different Formats\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Files to convert\r\nfiles = [\r\n    \"document.pdf\",\r\n    \"spreadsheet.xlsx\",\r\n    \"presentation.pptx\",\r\n    \"notes.docx\"\r\n]\r\n\r\nfor file in files:\r\n    try:\r\n        result = md.convert(file)\r\n        output = Path(file).stem + \".md\"\r\n        with open(output, \"w\") as f:\r\n            f.write(result.text_content)\r\n        print(f\"✓ Converted {file}\")\r\n    except Exception as e:\r\n        print(f\"✗ Error converting {file}: {e}\")\r\n```\r\n\r\n### 6. Extract YouTube Video Transcription\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert YouTube video to transcript\r\nresult = md.convert(\"https://www.youtube.com/watch?v=VIDEO_ID\")\r\nprint(result.text_content)\r\n```\r\n\r\n## Docker Usage\r\n\r\n```bash\r\n# Build image\r\ndocker build -t markitdown:latest .\r\n\r\n# Run conversion\r\ndocker run --rm -i markitdown:latest < ~/document.pdf > output.md\r\n```\r\n\r\n## Best Practices\r\n\r\n### 1. Choose the Right Conversion Method\r\n\r\n- **Simple documents**: Use basic `MarkItDown()`\r\n- **Complex PDFs**: Use Azure Document Intelligence\r\n- **Visual content**: Enable AI image descriptions\r\n- **Scanned documents**: Ensure OCR dependencies are installed\r\n\r\n### 2. Handle Errors Gracefully\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\ntry:\r\n    result = md.convert(\"document.pdf\")\r\n    print(result.text_content)\r\nexcept FileNotFoundError:\r\n    print(\"File not found\")\r\nexcept Exception as e:\r\n    print(f\"Conversion error: {e}\")\r\n```\r\n\r\n### 3. Process Large Files Efficiently\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# For large files, use streaming\r\nwith open(\"large_file.pdf\", \"rb\") as f:\r\n    result = md.convert_stream(f, file_extension=\".pdf\")\r\n    \r\n    # Process in chunks or save directly\r\n    with open(\"output.md\", \"w\") as out:\r\n        out.write(result.text_content)\r\n```\r\n\r\n### 4. Optimize for Token Efficiency\r\n\r\nMarkdown output is already token-efficient, but you can:\r\n- Remove excessive whitespace\r\n- Consolidate similar sections\r\n- Strip metadata if not needed\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport re\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"document.pdf\")\r\n\r\n# Clean up extra whitespace\r\nclean_text = re.sub(r'\\n{3,}', '\\n\\n', result.text_content)\r\nclean_text = clean_text.strip()\r\n\r\nprint(clean_text)\r\n```\r\n\r\n## Integration with Scientific Workflows\r\n\r\n### Convert Literature for Review\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert all papers in literature folder\r\npapers_dir = Path(\"literature/pdfs\")\r\noutput_dir = Path(\"literature/markdown\")\r\noutput_dir.mkdir(exist_ok=True)\r\n\r\nfor paper in papers_dir.glob(\"*.pdf\"):\r\n    result = md.convert(str(paper))\r\n    \r\n    # Save with metadata\r\n    output_file = output_dir / f\"{paper.stem}.md\"\r\n    content = f\"# {paper.stem}\\n\\n\"\r\n    content += f\"**Source**: {paper.name}\\n\\n\"\r\n    content += \"---\\n\\n\"\r\n    content += result.text_content\r\n    \r\n    output_file.write_text(content)\r\n\r\n# For AI-enhanced conversion with figures\r\nfrom openai import OpenAI\r\n\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd_ai = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",\r\n    llm_prompt=\"Describe scientific figures with technical precision\"\r\n)\r\n```\r\n\r\n### Extract Tables for Analysis\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport re\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"data_tables.xlsx\")\r\n\r\n# Markdown tables can be parsed or used directly\r\nprint(result.text_content)\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Missing dependencies**: Install feature-specific packages\r\n   ```bash\r\n   pip install 'markitdown[pdf]'  # For PDF support\r\n   ```\r\n\r\n2. **Binary file errors**: Ensure files are opened in binary mode\r\n   ```python\r\n   with open(\"file.pdf\", \"rb\") as f:  # Note the \"rb\"\r\n       result = md.convert_stream(f, file_extension=\".pdf\")\r\n   ```\r\n\r\n3. **OCR not working**: Install tesseract\r\n   ```bash\r\n   # macOS\r\n   brew install tesseract\r\n   \r\n   # Ubuntu\r\n   sudo apt-get install tesseract-ocr\r\n   ```\r\n\r\n## Performance Considerations\r\n\r\n- **PDF files**: Large PDFs may take time; consider page ranges if supported\r\n- **Image OCR**: OCR processing is CPU-intensive\r\n- **Audio transcription**: Requires additional compute resources\r\n- **AI image descriptions**: Requires API calls (costs may apply)\r\n\r\n## Next Steps\r\n\r\n- See `references/api_reference.md` for complete API documentation\r\n- Check `references/file_formats.md` for format-specific details\r\n- Review `scripts/batch_convert.py` for automation examples\r\n- Explore `scripts/convert_with_ai.py` for AI-enhanced conversions\r\n\r\n## Resources\r\n\r\n- **MarkItDown GitHub**: https://github.com/microsoft/markitdown\r\n- **PyPI**: https://pypi.org/project/markitdown/\r\n- **OpenRouter**: https://openrouter.ai (for AI-enhanced conversions)\r\n- **OpenRouter API Keys**: https://openrouter.ai/keys\r\n- **OpenRouter Models**: https://openrouter.ai/models\r\n- **MCP Server**: markitdown-mcp (for Claude Desktop integration)\r\n- **Plugin Development**: See `packages/markitdown-sample-plugin`",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The markitdown/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/markitdown",
    "exported_at": "2026-11-03T07:42:30.758Z"
  }
}

format: aiskill/v1
skill:
  name: markitdown
  slug: markitdown
  version: 1.0.0
  description: >-
    Convert files and office documents to Markdown. Supports PDF, DOCX, PPTX, XLSX, images (with
    OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs and more.
  category: Research
  tags:
    - research-science
    - documents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT LICENSE
prompts:
  system: "# MarkItDown - File to Markdown Conversion\r\n\r\n## Overview\r\n\r\nMarkItDown is a Python tool developed by Microsoft for converting various file formats to Markdown. It's particularly useful for converting documents into LLM-friendly text format, as Markdown is token-efficient and well-understood by modern language models.\r\n\r\n**Key Benefits**:\r\n- Convert documents to clean, structured Markdown\r\n- Token-efficient format for LLM processing\r\n- Supports 15+ file formats\r\n- Optional AI-enhanced image descriptions\r\n- OCR for images and scanned documents\r\n- Speech transcription for audio files\r\n\r\n## Visual Enhancement with Scientific Schematics\r\n\r\n**When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**\r\n\r\nIf your document does not already contain schematics or diagrams:\r\n- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams\r\n- Simply describe your desired diagram in natural language\r\n- Nano Banana Pro will automatically generate, review, and refine the schematic\r\n\r\n**For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.\r\n\r\n**How to generate schematics:**\r\n```bash\r\npython scripts/generate_schematic.py \"your diagram description\" -o figures/output.png\r\n```\r\n\r\nThe AI will automatically:\r\n- Create publication-quality images with proper formatting\r\n- Review and refine through multiple iterations\r\n- Ensure accessibility (colorblind-friendly, high contrast)\r\n- Save outputs in the figures/ directory\r\n\r\n**When to add schematics:**\r\n- Document conversion workflow diagrams\r\n- File format architecture illustrations\r\n- OCR processing pipeline diagrams\r\n- Integration workflow visualizations\r\n- System architecture diagrams\r\n- Data flow diagrams\r\n- Any complex concept that benefits from visualization\r\n\r\nFor detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.\r\n\r\n---\r\n\r\n## Supported Formats\r\n\r\n| Format | Description | Notes |\r\n|--------|-------------|-------|\r\n| **PDF** | Portable Document Format | Full text extraction |\r\n| **DOCX** | Microsoft Word | Tables, formatting preserved |\r\n| **PPTX** | PowerPoint | Slides with notes |\r\n| **XLSX** | Excel spreadsheets | Tables and data |\r\n| **Images** | JPEG, PNG, GIF, WebP | EXIF metadata + OCR |\r\n| **Audio** | WAV, MP3 | Metadata + transcription |\r\n| **HTML** | Web pages | Clean conversion |\r\n| **CSV** | Comma-separated values | Table format |\r\n| **JSON** | JSON data | Structured representation |\r\n| **XML** | XML documents | Structured format |\r\n| **ZIP** | Archive files | Iterates contents |\r\n| **EPUB** | E-books | Full text extraction |\r\n| **YouTube** | Video URLs | Fetch transcriptions |\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\n# Install with all features\r\npip install 'markitdown[all]'\r\n\r\n# Or from source\r\ngit clone https://github.com/microsoft/markitdown.git\r\ncd markitdown\r\npip install -e 'packages/markitdown[all]'\r\n```\r\n\r\n### Command-Line Usage\r\n\r\n```bash\r\n# Basic conversion\r\nmarkitdown document.pdf > output.md\r\n\r\n# Specify output file\r\nmarkitdown document.pdf -o output.md\r\n\r\n# Pipe content\r\ncat document.pdf | markitdown > output.md\r\n\r\n# Enable plugins\r\nmarkitdown --list-plugins  # List available plugins\r\nmarkitdown --use-plugins document.pdf -o output.md\r\n```\r\n\r\n### Python API\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\n# Basic usage\r\nmd = MarkItDown()\r\nresult = md.convert(\"document.pdf\")\r\nprint(result.text_content)\r\n\r\n# Convert from stream\r\nwith open(\"document.pdf\", \"rb\") as f:\r\n    result = md.convert_stream(f, file_extension=\".pdf\")\r\n    print(result.text_content)\r\n```\r\n\r\n## Advanced Features\r\n\r\n### 1. AI-Enhanced Image Descriptions\r\n\r\nUse LLMs via OpenRouter to generate detailed image descriptions (for PPTX and image files):\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom openai import OpenAI\r\n\r\n# Initialize OpenRouter client (OpenAI-compatible API)\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",  # recommended for scientific vision\r\n    llm_prompt=\"Describe this image in detail for scientific documentation\"\r\n)\r\n\r\nresult = md.convert(\"presentation.pptx\")\r\nprint(result.text_content)\r\n```\r\n\r\n### 2. Azure Document Intelligence\r\n\r\nFor enhanced PDF conversion with Microsoft Document Intelligence:\r\n\r\n```bash\r\n# Command line\r\nmarkitdown document.pdf -o output.md -d -e \"<document_intelligence_endpoint>\"\r\n```\r\n\r\n```python\r\n# Python API\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown(docintel_endpoint=\"<document_intelligence_endpoint>\")\r\nresult = md.convert(\"complex_document.pdf\")\r\nprint(result.text_content)\r\n```\r\n\r\n### 3. Plugin System\r\n\r\nMarkItDown supports 3rd-party plugins for extending functionality:\r\n\r\n```bash\r\n# List installed plugins\r\nmarkitdown --list-plugins\r\n\r\n# Enable plugins\r\nmarkitdown --use-plugins file.pdf -o output.md\r\n```\r\n\r\nFind plugins on GitHub with hashtag: `#markitdown-plugin`\r\n\r\n## Optional Dependencies\r\n\r\nControl which file formats you support:\r\n\r\n```bash\r\n# Install specific formats\r\npip install 'markitdown[pdf, docx, pptx]'\r\n\r\n# All available options:\r\n# [all]                  - All optional dependencies\r\n# [pptx]                 - PowerPoint files\r\n# [docx]                 - Word documents\r\n# [xlsx]                 - Excel spreadsheets\r\n# [xls]                  - Older Excel files\r\n# [pdf]                  - PDF documents\r\n# [outlook]              - Outlook messages\r\n# [az-doc-intel]         - Azure Document Intelligence\r\n# [audio-transcription]  - WAV and MP3 transcription\r\n# [youtube-transcription] - YouTube video transcription\r\n```\r\n\r\n## Common Use Cases\r\n\r\n### 1. Convert Scientific Papers to Markdown\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert PDF paper\r\nresult = md.convert(\"research_paper.pdf\")\r\nwith open(\"paper.md\", \"w\") as f:\r\n    f.write(result.text_content)\r\n```\r\n\r\n### 2. Extract Data from Excel for Analysis\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"data.xlsx\")\r\n\r\n# Result will be in Markdown table format\r\nprint(result.text_content)\r\n```\r\n\r\n### 3. Process Multiple Documents\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport os\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Process all PDFs in a directory\r\npdf_dir = Path(\"papers/\")\r\noutput_dir = Path(\"markdown_output/\")\r\noutput_dir.mkdir(exist_ok=True)\r\n\r\nfor pdf_file in pdf_dir.glob(\"*.pdf\"):\r\n    result = md.convert(str(pdf_file))\r\n    output_file = output_dir / f\"{pdf_file.stem}.md\"\r\n    output_file.write_text(result.text_content)\r\n    print(f\"Converted: {pdf_file.name}\")\r\n```\r\n\r\n### 4. Convert PowerPoint with AI Descriptions\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom openai import OpenAI\r\n\r\n# Use OpenRouter for access to multiple AI models\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",  # recommended for presentations\r\n    llm_prompt=\"Describe this slide image in detail, focusing on key visual elements and data\"\r\n)\r\n\r\nresult = md.convert(\"presentation.pptx\")\r\nwith open(\"presentation.md\", \"w\") as f:\r\n    f.write(result.text_content)\r\n```\r\n\r\n### 5. Batch Convert with Different Formats\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Files to convert\r\nfiles = [\r\n    \"document.pdf\",\r\n    \"spreadsheet.xlsx\",\r\n    \"presentation.pptx\",\r\n    \"notes.docx\"\r\n]\r\n\r\nfor file in files:\r\n    try:\r\n        result = md.convert(file)\r\n        output = Path(file).stem + \".md\"\r\n        with open(output, \"w\") as f:\r\n            f.write(result.text_content)\r\n        print(f\"✓ Converted {file}\")\r\n    except Exception as e:\r\n        print(f\"✗ Error converting {file}: {e}\")\r\n```\r\n\r\n### 6. Extract YouTube Video Transcription\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert YouTube video to transcript\r\nresult = md.convert(\"https://www.youtube.com/watch?v=VIDEO_ID\")\r\nprint(result.text_content)\r\n```\r\n\r\n## Docker Usage\r\n\r\n```bash\r\n# Build image\r\ndocker build -t markitdown:latest .\r\n\r\n# Run conversion\r\ndocker run --rm -i markitdown:latest < ~/document.pdf > output.md\r\n```\r\n\r\n## Best Practices\r\n\r\n### 1. Choose the Right Conversion Method\r\n\r\n- **Simple documents**: Use basic `MarkItDown()`\r\n- **Complex PDFs**: Use Azure Document Intelligence\r\n- **Visual content**: Enable AI image descriptions\r\n- **Scanned documents**: Ensure OCR dependencies are installed\r\n\r\n### 2. Handle Errors Gracefully\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\ntry:\r\n    result = md.convert(\"document.pdf\")\r\n    print(result.text_content)\r\nexcept FileNotFoundError:\r\n    print(\"File not found\")\r\nexcept Exception as e:\r\n    print(f\"Conversion error: {e}\")\r\n```\r\n\r\n### 3. Process Large Files Efficiently\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\n\r\nmd = MarkItDown()\r\n\r\n# For large files, use streaming\r\nwith open(\"large_file.pdf\", \"rb\") as f:\r\n    result = md.convert_stream(f, file_extension=\".pdf\")\r\n    \r\n    # Process in chunks or save directly\r\n    with open(\"output.md\", \"w\") as out:\r\n        out.write(result.text_content)\r\n```\r\n\r\n### 4. Optimize for Token Efficiency\r\n\r\nMarkdown output is already token-efficient, but you can:\r\n- Remove excessive whitespace\r\n- Consolidate similar sections\r\n- Strip metadata if not needed\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport re\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"document.pdf\")\r\n\r\n# Clean up extra whitespace\r\nclean_text = re.sub(r'\\n{3,}', '\\n\\n', result.text_content)\r\nclean_text = clean_text.strip()\r\n\r\nprint(clean_text)\r\n```\r\n\r\n## Integration with Scientific Workflows\r\n\r\n### Convert Literature for Review\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nfrom pathlib import Path\r\n\r\nmd = MarkItDown()\r\n\r\n# Convert all papers in literature folder\r\npapers_dir = Path(\"literature/pdfs\")\r\noutput_dir = Path(\"literature/markdown\")\r\noutput_dir.mkdir(exist_ok=True)\r\n\r\nfor paper in papers_dir.glob(\"*.pdf\"):\r\n    result = md.convert(str(paper))\r\n    \r\n    # Save with metadata\r\n    output_file = output_dir / f\"{paper.stem}.md\"\r\n    content = f\"# {paper.stem}\\n\\n\"\r\n    content += f\"**Source**: {paper.name}\\n\\n\"\r\n    content += \"---\\n\\n\"\r\n    content += result.text_content\r\n    \r\n    output_file.write_text(content)\r\n\r\n# For AI-enhanced conversion with figures\r\nfrom openai import OpenAI\r\n\r\nclient = OpenAI(\r\n    api_key=\"your-openrouter-api-key\",\r\n    base_url=\"https://openrouter.ai/api/v1\"\r\n)\r\n\r\nmd_ai = MarkItDown(\r\n    llm_client=client,\r\n    llm_model=\"anthropic/claude-opus-4.5\",\r\n    llm_prompt=\"Describe scientific figures with technical precision\"\r\n)\r\n```\r\n\r\n### Extract Tables for Analysis\r\n\r\n```python\r\nfrom markitdown import MarkItDown\r\nimport re\r\n\r\nmd = MarkItDown()\r\nresult = md.convert(\"data_tables.xlsx\")\r\n\r\n# Markdown tables can be parsed or used directly\r\nprint(result.text_content)\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Missing dependencies**: Install feature-specific packages\r\n   ```bash\r\n   pip install 'markitdown[pdf]'  # For PDF support\r\n   ```\r\n\r\n2. **Binary file errors**: Ensure files are opened in binary mode\r\n   ```python\r\n   with open(\"file.pdf\", \"rb\") as f:  # Note the \"rb\"\r\n       result = md.convert_stream(f, file_extension=\".pdf\")\r\n   ```\r\n\r\n3. **OCR not working**: Install tesseract\r\n   ```bash\r\n   # macOS\r\n   brew install tesseract\r\n   \r\n   # Ubuntu\r\n   sudo apt-get install tesseract-ocr\r\n   ```\r\n\r\n## Performance Considerations\r\n\r\n- **PDF files**: Large PDFs may take time; consider page ranges if supported\r\n- **Image OCR**: OCR processing is CPU-intensive\r\n- **Audio transcription**: Requires additional compute resources\r\n- **AI image descriptions**: Requires API calls (costs may apply)\r\n\r\n## Next Steps\r\n\r\n- See `references/api_reference.md` for complete API documentation\r\n- Check `references/file_formats.md` for format-specific details\r\n- Review `scripts/batch_convert.py` for automation examples\r\n- Explore `scripts/convert_with_ai.py` for AI-enhanced conversions\r\n\r\n## Resources\r\n\r\n- **MarkItDown GitHub**: https://github.com/microsoft/markitdown\r\n- **PyPI**: https://pypi.org/project/markitdown/\r\n- **OpenRouter**: https://openrouter.ai (for AI-enhanced conversions)\r\n- **OpenRouter API Keys**: https://openrouter.ai/keys\r\n- **OpenRouter Models**: https://openrouter.ai/models\r\n- **MCP Server**: markitdown-mcp (for Claude Desktop integration)\r\n- **Plugin Development**: See `packages/markitdown-sample-plugin`"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The markitdown/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/markitdown
  exported_at: "2026-11-03T07:42:30.758Z"