markitdown-reader

Markitdown Reader

Convert binary and token-heavy files to markdown before reading. Uses the markitdown CLI to produce clean .md output that is cheaper and easier to parse than raw binary formats.

Core principle: Never read a binary or large-format file directly when a lightweight markdown conversion exists.

When to Use

• •User provides or references a PDF, DOCX, PPTX, XLSX, XLS, HTML, ZIP, MSG, audio file, or YouTube link
• •File is too large or token-expensive to read natively
• •Format cannot be read natively (PPTX, DOCX, XLS, MSG)
• •User asks to read/summarize/analyze a document in a supported format

Do NOT use when:

• •File is already plain text, markdown, or source code
• •File is a small image (use native image reading)
• •User explicitly asks for raw/native reading
• •PDF is under 5 pages (native PDF reading is fine for small files)

Supported Formats

Procedure

1. Check markitdown installed  →  which markitdown || pip install markitdown[all]
2. Convert to markdown          →  markitdown "<path>" > /tmp/<name>.md 2>/tmp/<name>_err.log
3. Validate output              →  wc -l /tmp/<name>.md (must be > 0 lines)
4. Check output size            →  wc -c /tmp/<name>.md (if > 500KB, read with offset/limit)
5. Read converted file          →  Read tool on /tmp/<name>.md
6. On failure                   →  check /tmp/<name>_err.log, see Error Handling below

Conversion Command

# Always redirect stderr to catch errors
markitdown "/path/to/file.pdf" > /tmp/file.md 2>/tmp/file_err.log

# Check conversion succeeded
if [ ! -s /tmp/file.md ]; then
  cat /tmp/file_err.log
fi

Large Output Handling

If converted markdown exceeds ~500KB or ~10,000 lines:

• •Use Read with offset and limit to read in chunks
• •Summarize sections as you go, don't load everything into context
• •Tell user about file size before reading: "Document converted to X lines of markdown. Reading relevant sections."

Quick Reference

Error Handling

Fallback Strategy

If markitdown fails and no fix works:

1. PDF → try native Read tool (works for small PDFs up to ~10 pages)
2. XLSX → try python3 -c "import openpyxl; ..." to extract specific sheets
3. DOCX → try python3 -c "import docx; ..." to extract raw text
4. Audio → suggest user provide a transcript manually
5. Always inform user of the failure and what you tried

Common Mistakes

Installation

# All formats (recommended)
pip install markitdown[all]

# Audio also needs ffmpeg
brew install ffmpeg  # macOS