Document Converter (MarkItDown)
Convert Office and structured documents to Markdown for LLM consumption using Microsoft MarkItDown.
Overview
MarkItDown is a Microsoft open-source tool that converts a wide range of document formats into clean Markdown text. This is essential for academic research workflows where source materials arrive in diverse formats (PDFs from journals, PPTX from conferences, DOCX from collaborators, XLSX data tables).
Supported Formats
| Format |
Extensions |
Notes |
| PDF |
.pdf |
Text extraction; scanned PDFs require OCR |
| Word |
.docx |
Paragraphs, tables, lists, headings preserved |
| PowerPoint |
.pptx |
Slide-by-slide with speaker notes |
| Excel |
.xlsx, .xls |
Sheet-by-sheet, tables as Markdown tables |
| HTML |
.html, .htm |
Cleaned content extraction |
| CSV |
.csv |
Converted to Markdown table |
| JSON |
.json |
Pretty-printed structured output |
| XML |
.xml |
Structured text extraction |
| Images |
.jpg, .png, .gif, .bmp, .tiff |
OCR text extraction (requires optional deps) |
| Audio |
.mp3, .wav |
Transcription (requires optional deps) |
| ZIP |
.zip |
Recursively converts contained files |
MCP Tool Usage
When the markitdown-mcp server is configured, use the convert_to_markdown tool:
Tool: convert_to_markdown
Parameters:
uri: "file:///absolute/path/to/document.pptx"
The uri parameter accepts:
- Local files:
file:///path/to/file.docx
- HTTP URLs:
https://example.com/paper.pdf
Important
- Always use absolute paths with the
file:// URI scheme for local files.
- The tool returns the full Markdown text content of the converted document.
- For large documents, the output may be substantial. Consider summarizing or extracting relevant sections after conversion.
CLI Fallback
If the MCP server is not available, use the CLI directly via shell:
# Convert a single file
markitdown document.pptx
# Save output to file
markitdown document.pptx > output.md
# Convert from URL
markitdown https://example.com/paper.pdf
Academic Research Workflows
1. Conference Presentation Analysis
Convert a PPTX to Markdown, then analyze the content:
- Convert the presentation with
convert_to_markdown
- The output preserves slide structure and speaker notes
- Summarize key findings, methodology, and conclusions
2. Paper Review from PDF
- Convert the PDF to Markdown
- Extract sections: Abstract, Introduction, Methods, Results, Discussion
- Cross-reference with literature library
3. Data Table Extraction
- Convert XLSX to Markdown tables
- Each sheet becomes a separate section
- Use the extracted tables for analysis or comparison
4. Batch Literature Processing
When processing multiple documents:
- Convert each document individually
- Extract metadata (title, authors, date) from the content
- Add to the literature library with
library_add_paper
Output Quality Notes
| Format |
Quality |
Caveats |
| DOCX |
Excellent |
Complex layouts may lose formatting |
| PPTX |
Good |
Diagrams/charts become text descriptions |
| XLSX |
Good |
Merged cells may not render perfectly |
| PDF |
Variable |
Depends on PDF type (text vs scanned) |
| HTML |
Good |
JavaScript-rendered content not captured |
| CSV |
Excellent |
Direct table conversion |
When to Use This Skill
- User uploads or references an Office document (PPTX, DOCX, XLSX)
- User wants to analyze content from a PDF
- User needs to extract text from images (OCR)
- User wants to convert a document for inclusion in notes or workspace
- User asks to read, summarize, or analyze a non-Markdown file
- Batch processing of research materials in mixed formats
When NOT to Use
- File is already Markdown or plain text
- User wants to edit the original document format (use appropriate editor)
- User needs pixel-perfect layout preservation (use the original format)
- File is a scanned PDF without OCR support configured
Troubleshooting
| Issue |
Solution |
markitdown not found |
Run pip install 'markitdown[all]' |
| MCP tool not available |
Ensure markitdown-mcp is installed and configured in openclaw.json |
| Empty output from PDF |
PDF may be scanned/image-only; needs OCR dependencies |
| Encoding errors |
Ensure file is not corrupted; try re-saving from source application |
| Large file timeout |
Convert via CLI instead of MCP for very large files |
Installation
Local (macOS/Linux)
pip install 'markitdown[all]' markitdown-mcp
Verify
markitdown --help
Docker
MarkItDown is pre-installed in the Research-Claw Docker image.
1---
2name: document-converter
3description: Convert Office documents (PPTX, DOCX, XLSX, PDF, HTML, CSV, JSON, XML, images) to Markdown using Microsoft MarkItDown. Provides the agent with conversion strategies for academic and research workflows.
4tags: [document, conversion, markdown, office, pdf, pptx, docx]
5version: 1.0.0
6requirements:
7 - markitdown
8 - markitdown-mcp
9install: pip install 'markitdown[all]' markitdown-mcp
10---
11
12# Document Converter (MarkItDown)
13
14Convert Office and structured documents to Markdown for LLM consumption using Microsoft MarkItDown.
15
16---
17
18## Overview
19
20MarkItDown is a Microsoft open-source tool that converts a wide range of document formats into clean Markdown text. This is essential for academic research workflows where source materials arrive in diverse formats (PDFs from journals, PPTX from conferences, DOCX from collaborators, XLSX data tables).
21
22---
23
24## Supported Formats
25
26| Format | Extensions | Notes |
27|--------|-----------|-------|
28| PDF | `.pdf` | Text extraction; scanned PDFs require OCR |
29| Word | `.docx` | Paragraphs, tables, lists, headings preserved |
30| PowerPoint | `.pptx` | Slide-by-slide with speaker notes |
31| Excel | `.xlsx`, `.xls` | Sheet-by-sheet, tables as Markdown tables |
32| HTML | `.html`, `.htm` | Cleaned content extraction |
33| CSV | `.csv` | Converted to Markdown table |
34| JSON | `.json` | Pretty-printed structured output |
35| XML | `.xml` | Structured text extraction |
36| Images | `.jpg`, `.png`, `.gif`, `.bmp`, `.tiff` | OCR text extraction (requires optional deps) |
37| Audio | `.mp3`, `.wav` | Transcription (requires optional deps) |
38| ZIP | `.zip` | Recursively converts contained files |
39
40---
41
42## MCP Tool Usage
43
44When the `markitdown-mcp` server is configured, use the `convert_to_markdown` tool:
45
46```
47Tool: convert_to_markdown
48Parameters:
49 uri: "file:///absolute/path/to/document.pptx"
50```
51
52The `uri` parameter accepts:
53- Local files: `file:///path/to/file.docx`
54- HTTP URLs: `https://example.com/paper.pdf`
55
56### Important
57
58- Always use absolute paths with the `file://` URI scheme for local files.
59- The tool returns the full Markdown text content of the converted document.
60- For large documents, the output may be substantial. Consider summarizing or extracting relevant sections after conversion.
61
62---
63
64## CLI Fallback
65
66If the MCP server is not available, use the CLI directly via shell:
67
68```bash
69# Convert a single file
70markitdown document.pptx
71
72# Save output to file
73markitdown document.pptx > output.md
74
75# Convert from URL
76markitdown https://example.com/paper.pdf
77```
78
79---
80
81## Academic Research Workflows
82
83### 1. Conference Presentation Analysis
84
85Convert a PPTX to Markdown, then analyze the content:
86
871. Convert the presentation with `convert_to_markdown`
882. The output preserves slide structure and speaker notes
893. Summarize key findings, methodology, and conclusions
90
91### 2. Paper Review from PDF
92
931. Convert the PDF to Markdown
942. Extract sections: Abstract, Introduction, Methods, Results, Discussion
953. Cross-reference with literature library
96
97### 3. Data Table Extraction
98
991. Convert XLSX to Markdown tables
1002. Each sheet becomes a separate section
1013. Use the extracted tables for analysis or comparison
102
103### 4. Batch Literature Processing
104
105When processing multiple documents:
1061. Convert each document individually
1072. Extract metadata (title, authors, date) from the content
1083. Add to the literature library with `library_add_paper`
109
110---
111
112## Output Quality Notes
113
114| Format | Quality | Caveats |
115|--------|---------|---------|
116| DOCX | Excellent | Complex layouts may lose formatting |
117| PPTX | Good | Diagrams/charts become text descriptions |
118| XLSX | Good | Merged cells may not render perfectly |
119| PDF | Variable | Depends on PDF type (text vs scanned) |
120| HTML | Good | JavaScript-rendered content not captured |
121| CSV | Excellent | Direct table conversion |
122
123---
124
125## When to Use This Skill
126
127- User uploads or references an Office document (PPTX, DOCX, XLSX)
128- User wants to analyze content from a PDF
129- User needs to extract text from images (OCR)
130- User wants to convert a document for inclusion in notes or workspace
131- User asks to read, summarize, or analyze a non-Markdown file
132- Batch processing of research materials in mixed formats
133
134---
135
136## When NOT to Use
137
138- File is already Markdown or plain text
139- User wants to edit the original document format (use appropriate editor)
140- User needs pixel-perfect layout preservation (use the original format)
141- File is a scanned PDF without OCR support configured
142
143---
144
145## Troubleshooting
146
147| Issue | Solution |
148|-------|----------|
149| `markitdown` not found | Run `pip install 'markitdown[all]'` |
150| MCP tool not available | Ensure `markitdown-mcp` is installed and configured in `openclaw.json` |
151| Empty output from PDF | PDF may be scanned/image-only; needs OCR dependencies |
152| Encoding errors | Ensure file is not corrupted; try re-saving from source application |
153| Large file timeout | Convert via CLI instead of MCP for very large files |
154
155---
156
157## Installation
158
159### Local (macOS/Linux)
160
161```bash
162pip install 'markitdown[all]' markitdown-mcp
163```
164
165### Verify
166
167```bash
168markitdown --help
169```
170
171### Docker
172
173MarkItDown is pre-installed in the Research-Claw Docker image.
wentorai