MarkItDown: pasa cualquier documento a Markdown y ahorra tokens

Conocí MarkItDown por casualidad. Iba a pasarle un PDF de documentación técnica a un agente de Inteligencia Artificial, y sabía que el modelo iba a consumir una barbaridad de tokens procesando el formato original. Llevaba tiempo aplicando estrategias para optimizar el consumo, como las que ya conté en cómo reducir el consumo de tokens. Pero quería algo más automático, algo que hiciese la conversión por mí antes de que el modelo tocase el documento.

Buscando alternativas, encontré el repositorio de MarkItDown en GitHub. Más de 130.000 estrellas, mantenido por Microsoft, y con una descripción que prometía exactamente lo que necesitaba: convertir prácticamente cualquier formato de documento a Markdown. Lo probé en cinco minutos. Y sí, era exactamente lo que parecía.

¿Qué es MarkItDown?

MarkItDown es una herramienta de línea de comandos y biblioteca Python, open-source, creada por el equipo de AutoGen de Microsoft. Su propósito es convertir archivos de todo tipo a Markdown, pensando específicamente en que el resultado sea consumido por modelos de lenguaje grandes y pipelines de análisis de texto.

No es un conversor de documentos para humanos. No esperes una fidelidad perfecta con el diseño original de un PowerPoint o un Word. El objetivo es otro: preservar la estructura del documento (encabezados, listas, tablas, enlaces) en un formato que las inteligencias artificiales entienden de forma nativa. Y en eso, cumple de manera sobresaliente.

El proyecto está escrito en Python, tiene una licencia MIT, y su comunidad es activa. En el momento de escribir esto, cuenta con más de 300 contributors y casi 400 issues abiertas, lo que indica que el proyecto tiene tracción real.

Formatos que soporta

La lista de formatos es impresionante para ser una herramienta tan ligera:

Formato	Detalle
PDF	Conversión directa
PowerPoint (PPTX)	Diapositivas a Markdown
Word (DOCX)	Documentos completos
Excel (XLSX, XLS)	Hojas a tablas Markdown
Imágenes	Metadatos EXIF y OCR
Audio	Metadatos EXIF y transcripción de voz
HTML	Conversión directa
CSV, JSON, XML	Formateados como Markdown
ZIP	Itera sobre los contenidos
URLs de YouTube	Transcripción del vídeo
EPubs	Libros electrónicos

Cada formato tiene dependencias opcionales. No necesitas instalar todo si solo vas a trabajar con PDFs y Word. Puedes instalar solo lo que necesites:

pip install 'markitdown[pdf, docx]'

Por qué Markdown para Inteligencia Artificial

Los modelos de lenguaje grandes entienden Markdown de forma nativa. De hecho, si usas cualquier modelo moderno, habrás notado que sus respuestas incluyen Markdown sin que se lo pidas. Eso es porque han sido entrenados con cantidades ingentes de texto en ese formato.

Markdown tiene dos ventajas clave frente a pasar el documento original:

Eficiencia de tokens. Un PDF tiene metadatos, fuentes incrustadas, estructura de página, imágenes codificadas y mil cosas más que no aportan nada al contenido relevante. Al convertirlo a Markdown, eliminas todo ese ruido y te quedas solo con el texto y su estructura. Dependiendo del documento, puedes reducir el tamaño entre un 40 y un 70 por ciento. En documentos con muchas imágenes o formato complejo, el ahorro es aún mayor.

Claridad semántica. Los encabezados, listas y tablas en Markdown transmiten la misma jerarquía que el documento original. La Inteligencia Artificial entiende que lo que está bajo un ## es un subtema, no un párrafo suelto. Esto mejora la calidad de las respuestas porque el modelo capta la estructura del documento.

Ya escribí un post completo sobre por qué el formato de entrada es una de las variables que más impacto tiene en el consumo: cómo reducir el consumo de tokens en Claude Code.

Instalación

La instalación es directa con pip.

pip install 'markitdown[all]'

Si quieres instalarlo desde el código fuente:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Requiere Python 3.10 o superior. Nada más.

Uso

Línea de comandos

El caso más sencillo: convertir un archivo y volcar la salida a otro archivo.

markitdown documento.pdf > salida.md

O especificando el archivo de salida directamente:

markitdown documento.pdf -o salida.md

También puedes pipear contenido:

cat documento.pdf | markitdown

API de Python

Si necesitas integrarlo en un script o automatización:

from markitdown import MarkItDown

md = MarkItDown()
resultado = md.convert("informe.xlsx")
print(resultado.text_content)

Con descripciones de imágenes usando IA

Si quieres que además describa las imágenes que encuentra, puedes pasarle un cliente de OpenAI:

from markitdown import MarkItDown
from openai import OpenAI

cliente = OpenAI()
md = MarkItDown(llm_client=cliente, llm_model="gpt-4o")
resultado = md.convert("presentacion.pptx")
print(resultado.text_content)

Esto es especialmente útil para PowerPoints o PDFs con muchas capturas de pantalla o diagramas.

Con Document Intelligence de Azure

Si trabajas con Azure, también puedes usar Document Intelligence para conversiones más avanzadas:

markitdown path-to-file.pdf -o documento.md -d -e "<endpoint>"

Con Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/archivo.pdf > salida.md

Plugins

MarkItDown soporta plugins de terceros. Por ahora el más interesante es markitdown-ocr, que añade OCR a PDFs, DOCX, PPTX y XLSX usando visión por LLM.

pip install markitdown-ocr
pip install openai

Y se activa al inicializar MarkItDown con enable_plugins=True:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
resultado = md.convert("documento_con_imagenes.pdf")

Mi caso de uso

El escenario que me llevó a MarkItDown es simple pero muy efectivo: cuando tengo que pasarle un documento grande a un agente de Inteligencia Artificial, lo convierto primero a Markdown. No solo reduzco el número de tokens, sino que además el modelo entiende mejor la estructura del documento.

Pongamos un ejemplo concreto. Un PDF de especificaciones técnicas de 50 páginas, con tablas, diagramas y capturas de pantalla. Si se lo pasas directamente a un LLM, el modelo tiene que procesar el formato PDF, los saltos de página, las fuentes, los metadatos, las imágenes codificadas en base64… todo eso son tokens que no aportan valor. Con MarkItDown, obtienes el mismo contenido en Markdown limpio, con sus encabezados, listas y tablas intactos, y consumes muchos menos tokens.

Esto es especialmente útil cuando trabajas con agentes que tienen ventanas de contexto limitadas. Si tu contexto máximo es de 200.000 tokens y el PDF ocupa 80.000 después de la conversión a Markdown, te quedan 120.000 tokens para instrucciones, ejemplos y el diálogo. Si el PDF ocupa 160.000 tokens en bruto, te quedan solo 40.000. La diferencia es abismal.

En mi flujo de trabajo, se ha convertido en un paso automático antes de cualquier interacción con documentos largos. Un script que recibe el archivo, lo pasa por MarkItDown, y el resultado se lo envía al agente. Sencillo, rápido y efectivo.

Alternativas

MarkItDown no es la única herramienta que hace esto, pero sí la que mejor equilibrio ofrece entre soporte de formatos y simplicidad. Textract también convierte múltiples formatos pero no genera Markdown, solo texto plano. Pandoc es el rey de las conversiones entre formatos, pero requiere conocer sus filtros y opciones, y no está pensado específicamente para el consumo por LLMs.

MarkItDown ocupa un nicho muy concreto: convertir a Markdown para inteligencias artificiales. Y en eso, es difícil de superar.

Preguntas frecuentes

¿MarkItDown es gratis?

Sí. Es un proyecto open-source con licencia MIT mantenido por Microsoft. Puedes usarlo, modificarlo e integrarlo en tus proyectos sin coste alguno.

¿Qué formatos soporta MarkItDown?

PDF, Word (DOCX), PowerPoint (PPTX), Excel (XLSX/XLS), HTML, CSV, JSON, XML, ZIP, EPub, imágenes (con OCR y metadatos EXIF), audio (transcripción) e incluso URLs de YouTube (transcripción del vídeo).

¿Por qué convertir un documento a Markdown antes de pasarlo a la Inteligencia Artificial?

Porque eliminas el ruido del formato original (metadatos, fuentes, imágenes codificadas) y conservas solo el texto y su estructura. Dependiendo del documento, reduces el tamaño entre un 40 y un 70 por ciento y el modelo entiende mejor la jerarquía del contenido.

¿MarkItDown necesita conexión a internet o una API de pago?

No para la conversión básica: funciona en local. Solo necesitas un cliente de OpenAI o Azure Document Intelligence si quieres que además describa imágenes o aplique OCR mediante visión por LLM.

Fuentes

Compártelo si te ha resultado útil.

¿Ya conocías MarkItDown? ¿Tienes algún otro método para preparar documentos antes de pasarlos a la Inteligencia Artificial? Cuéntame.

Y… a convertir toca.