MarkItDown: convierte cualquier archivo en contexto limpio para Claude

Le pegas un PDF de 30 páginas a Claude Code y la mitad del contexto se va en tablas rotas y caracteres raros. MarkItDown es una librería Python open source de Microsoft (MIT) que convierte casi cualquier formato a Markdown limpio — pensada explícitamente como pre-procesador de contexto para LLMs.

Qué convierte

Office: Word (.docx), Excel (.xlsx), PowerPoint (.pptx).
PDF (texto + tablas).
Imágenes con OCR (y descripción opcional vía LLM).
Audio con transcripción automática.
HTML, EPUB, ZIP, CSV, JSON, XML.

Instalación

Dos comandos. El primero instala la librería con todos los conversores; el segundo es el binario CLI que vas a usar desde terminal.

pip install 'markitdown[all]'
markitdown --help

Si solo quieres lo básico (sin OCR/audio) puedes hacer pip install markitdown y luego ir añadiendo extras (pip install 'markitdown[pdf]', [docx], [audio-transcription], etc.).

Uso mínimo

Un archivo, una línea. Redirige el output a un .md y ya lo tienes listo para pegar.

markitdown informe.pdf > informe.md
markitdown reunion.mp3 > reunion.md
markitdown propuesta.docx > propuesta.md

Snippet para tu `CLAUDE.md`

El patrón que funciona: declarar MarkItDown como herramienta de pre-proceso de archivos grandes, antes de que Claude se los lea. Ahorras tokens y le evitas tener que parsear formato sucio.

Pega esto en tu CLAUDE.md:

## Pre-proceso de archivos

Antes de leer un archivo en formato no-texto (PDF, DOCX, XLSX, PPTX, EPUB, audio, imagen), conviértelo primero a markdown con:

    markitdown <archivo> > <archivo>.md

Lee el `.md` resultante en lugar del original. Esto reduce el ruido (formato, encoding) y baja el consumo de contexto entre un 30% y un 60% según el archivo.

A partir de ahí, cuando le pidas a Claude Code “léete este PDF y resúmelo”, lo que va a hacer es ejecutar markitdown informe.pdf > informe.md y leer el .md — no el PDF en bruto.

Flags que merece la pena conocer

Flag	Para qué
`-o <archivo>`	Output a fichero (en vez de redirigir con `>`).
`--use-docintel <endpoint>`	Activa Azure Document Intelligence para PDF/imágenes con tablas complejas. Requiere endpoint Azure.
`--use-llm`	Usa un LLM para describir imágenes embebidas (alt text generado).
`--llm-model <modelo>`	Modelo a usar con `--use-llm` (ej. `gpt-4o`).
`--keep-data-uris`	Mantiene imágenes embebidas como base64 (útil si vas a renderizar el `.md` después).

Default sin flags = OCR/transcripción local con los conversores incluidos. Para el 80% de los casos basta.

Cuándo NO usarlo

Archivos ya en markdown o texto plano. Es un paso extra innecesario.
PDFs escaneados de calidad muy baja. El OCR local fallará. Mejor usar --use-docintel o pre-procesar la imagen aparte.
Documentos con layout muy visual (revistas, presentaciones cargadas de gráficos): el output será texto plano sin el layout. Lo que sí extraerá es el contenido textual y las tablas.

La regla de oro

Si Claude Code te dice que un archivo es “demasiado grande” o el resumen sale confuso, no es Claude — es el formato que le has metido. Cambia el formato, no el prompt.

Repo oficial → github.com/microsoft/markitdown

Sígueme para más trucos con Claude Code e IA → @pabloinpublic

Waitlist de la comunidad → pabloinpublic.com