---
name: markitdown
description: Universal document and media converter powered by Microsoft MarkItDown. Converts PDF, Word (docx), Excel (xlsx), PowerPoint (pptx), HTML, CSV, audio, and images to clean, structured Markdown. Use whenever you need to read, inspect, or extract text from PDFs, spreadsheets, office documents, or web files.
---

# 📄 Microsoft MarkItDown Converter

Convert arbitrary documents and files into clean, structured Markdown for analysis, summarization, or archiving.

## 🚀 Usage

Use `scripts/convert_to_markdown.py`. The script runs automatically via `uv` with all document dependencies bundled.

### 1. Convert a Remote URL (PDF, Word, etc.)
Download and convert in one step:
```bash
python3 scripts/convert_to_markdown.py --url "https://example.com/document.pdf"
```

To save directly to a file with frontmatter metadata:
```bash
python3 scripts/convert_to_markdown.py --url "https://example.com/document.pdf" --frontmatter -o /path/to/output.md
```

### 2. Convert a Local File
Convert an existing local document or an uploaded attachment:
```bash
python3 scripts/convert_to_markdown.py /path/to/invoice.pdf
python3 scripts/convert_to_markdown.py /path/to/spreadsheet.xlsx
python3 scripts/convert_to_markdown.py /path/to/presentation.pptx
```

## 🛠️ Supported Formats
* **PDF (`.pdf`)**: Extracts text, columns, formatting, and tables.
* **Microsoft Word (`.docx`)**: Preserves headers, bold/italic, lists, and tables.
* **Microsoft Excel (`.xlsx`)**: Converts sheets and tables into Markdown pipe tables.
* **Microsoft PowerPoint (`.pptx`)**: Extracts slide text, outlines, and speaker notes.
* **HTML / Web pages**: Cleans boilerplate and outputs article markdown.
* **CSV / JSON / XML**: Formats data into readable markdown tables or code blocks.
* **Audio (`.wav`, `.mp3`)**: Transcribes speech (when speech models are active).
* **Images**: Extracts metadata, EXIF details, and embedded text descriptions.

## 💡 Best Practices for OpenClaw
- When the user sends a PDF or document link in Telegram, call `convert_to_markdown.py --url <URL>` to read its contents before answering.
- For large documents (>50 pages), save the converted Markdown to a temporary file and search/filter for relevant sections.