CubeLabs

1. Qué es MarkItDown y por qué Markdown es el idioma de los LLMs

MarkItDown es una librería de Python que convierte archivos y documentos de oficina a Markdown. Se compara a sí misma con textract, pero con una diferencia de enfoque: mientras textract extrae texto plano, MarkItDown intenta preservar la estructura del documento como Markdown —encabezados, listas, tablas, enlaces— porque ese texto no es para leerlo: es para que lo consuma una herramienta de análisis de texto.

El proyecto es explícito sobre su límite: la salida es razonablemente legible por humanos, pero no es la mejor opción para conversión de alta fidelidad para consumo humano. Eso es una decisión de diseño, no un defecto: optimiza para lo que un LLM necesita.

¿Por qué Markdown y no texto plano o HTML?

El razonamiento del proyecto es sencillo y vale la pena interiorizarlo:

• Markdown está muy cerca de texto plano, con un marcado mínimo, pero sigue representando estructura importante.
• Los LLMs mainstream lo "hablan" de forma nativa: GPT-4o y compañía lo incorporan a sus respuestas sin que se lo pidas, lo que sugiere que se entrenaron con enormes cantidades de texto en Markdown y lo entienden bien.
• Como efecto secundario, las convenciones de Markdown son altamente eficientes en tokens. Menos tokens = menos coste y más documento dentro de la ventana de contexto.

Qué puede convertir

El soporte incluye formatos de oficina, multimedia y web:

Dos hechos de contexto que ayudan a situar el proyecto: nació dentro del ecosistema de AutoGen (lleva el badge Built by AutoGen Team) y sus topics oficiales en GitHub son autogen, langchain, openai, markdown, microsoft-office y pdf — es decir, está pensado para vivir dentro de aplicaciones y agentes, no para ser una app de escritorio.

2. Instalación y dependencias opcionales

MarkItDown requiere Python 3.10 o superior y se recomienda una máquina virtual para evitar conflictos de dependencias. El paquete se distribuye en PyPI como markitdown y su instalación completa es:

pip install 'markitdown[all]'

Alternativamente, desde el código fuente (útil si quieres contribuir o fijar un commit):

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

Preparar el entorno

Catálogo de extras

3. La CLI en acción: flags, pipes y conversión en lote

La interfaz de línea de comandos es la forma más directa de usar la herramienta. La forma canónica es escribir a stdout y redirigir:

markitdown ruta-al-archivo.pdf > documento.md

O usar -o para indicar el archivo de salida:

markitdown ruta-al-archivo.pdf -o documento.md

Y también acepta contenido por pipe:

cat ruta-al-archivo.pdf | markitdown

Salida real de una conversión

Esto es lo que devuelve MarkItDown al convertir un CSV, ejecutado de verdad durante la preparación de este curso:

$ markitdown ventas.csv
| producto | precio | stock |
| --- | --- | --- |
| Teclado mecanico | 89.90 | 12 |
| Monitor 27 pulgadas | 219.00 | 4 |
| SSD NVMe 1TB | 74.50 | 31 |

Fíjate en lo que ha ocurrido: el CSV se ha convertido en una tabla Markdown, no en texto separado por comas. Es exactamente el tipo de transformación que un LLM agradece.

Cuando el contenido llega por stdin sin nombre de archivo

Si no hay extensión que inspeccionar, se la das tú con pistas. Verificado en producción:

$ cat ventas.csv | markitdown -x csv
| producto | precio | stock |
| --- | --- | --- |
| Teclado mecanico | 89.90 | 12 |
| Monitor 27 pulgadas | 219.00 | 4 |
| SSD NVMe 1TB | 74.50 | 31 |

Referencia de flags

-d/--use-docintel y --use-cu son mutuamente excluyentes: el parser los declara en un grupo exclusivo, así que no puedes pedir las dos nubes a la vez.

Convertir una carpeta entera

Para pipelines reales, el patrón habitual es un bucle que respete la estructura de directorios:

mkdir -p salida
for f in documentos/*.pdf; do
  base=$(basename "$f" .pdf)
  markitdown "$f" -o "salida/$base.md"
done

4. La API de Python: convierte sin escribir en disco

El uso básico es de tres líneas. Se instancia MarkItDown y se llama a convert():

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)  # True para habilitar plugins
result = md.convert("test.xlsx")
print(result.markdown)

El objeto de resultado

La conversión devuelve un DocumentConverterResult con dos campos relevantes:

• result.markdown — el texto Markdown resultante. Es el campo que debes usar.
• result.title — título opcional del documento, si el conversor puede determinarlo (puede ser None).

El objeto también implementa __str__ devolviendo el Markdown, y existe text_content como alias en desuso: si lo ves en código antiguo, el código nuevo debe migrar a markdown.

Elige el método más estrecho posible

Este es el punto de seguridad más importante de todo el curso. MarkItDown hace E/S con los privilegios del proceso actual: igual que open() o requests.get(), accede a los recursos a los que el proceso tiene acceso. Por eso la API ofrece varios niveles de control:

Un ejemplo real de conversión desde un stream de bytes en memoria, verificado durante la preparación de este curso:

$ python3 - <<'EOF'
import io
from markitdown import MarkItDown

md = MarkItDown()
with open('ventas.csv', 'rb') as f:
    stream = io.BytesIO(f.read())

result = md.convert_stream(stream, stream_info=None)
print('tipo:', type(result).__name__)
print('title:', result.title)
print(result.markdown[:120])
EOF
tipo: DocumentConverterResult
title: None
| producto | precio | stock |
| --- | --- | --- |
| Teclado mecanico | 89.90 | 12 |
| Monitor 27 pulgadas | 219.00 | 4 |

Dos observaciones útiles de la salida: el tipo es DocumentConverterResult y el title es None porque un CSV no tiene título. Tu código debe estar preparado para que title venga vacío.

5. PDF, Word, PowerPoint y Excel: qué estructura se preserva

Los formatos de oficina son el caso de uso principal. Cada uno tiene su dependencia y sus particularidades:

Ejemplo real: de Excel a Markdown

Creamos un libro con una hoja llamada Q3 y dos filas de datos. Esto es exactamente lo que devuelve MarkItDown:

$ markitdown informe.xlsx
## Q3
| Region | Ingresos | Margen |
| --- | --- | --- |
| EMEA | 412000 | 0.31 |
| LATAM | 188500 | 0.27 |

El detalle importante: el nombre de la hoja se convierte en un encabezado de nivel 2 (## Q3). Eso significa que si concatenas varias hojas, un LLM puede atribuir cada tabla a su contexto sin ambigüedad. Los valores numéricos se mantienen tal cual, sin formateo añadido: el trabajo de interpretarlos es del modelo, no de la herramienta.

Ejemplo real: de HTML a Markdown

$ markitdown pagina.html
# Experimento 14

Medimos **latencia** con 3 modelos.

| Modelo | ms |
| --- | --- |
| A | 120 |
| B | 98 |

* Repetir 5 veces
* Anotar p95

Se ve la traducción directa: <h1> → #, <strong> → **, <table> → tabla Markdown, <ul><li> → lista con asteriscos.

6. Imágenes y audio: EXIF, OCR y descripciones con LLM Vision

MarkItDown no se limita a documentos. En imágenes extrae los metadatos EXIF (y OCR cuando está disponible) y, opcionalmente, genera descripciones con un LLM. En audio hace lo simétrico: metadatos EXIF y transcripción de voz.

Descripciones de imagen con un LLM

Para usar un modelo en la descripción de imágenes —actualmente para pptx y archivos de imagen— se le pasan llm_client y llm_model:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(max_retries=5)
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="opcional: un prompt personalizado",
)
result = md.convert("ejemplo.jpg")
print(result.markdown)

Tres detalles que marcan la diferencia en producción:

• max_retries controla los reintentos automáticos del cliente de OpenAI ante errores reintentables (el valor por defecto del SDK es 2; 5 permite hasta seis intentos con retroceso exponencial).
• Si algún intento tiene éxito, la conversión de la imagen continúa con normalidad.
• Si el cliente falla tras agotar los reintentos —o se topa con un error no reintentable— MarkItDown prueba otros conversores aplicables y solo lanza FileConversionException si ninguno tiene éxito.

Ese último comportamiento es la razón de que un pipeline pueda seguir funcionando cuando la API de vision falla: hay una cadena de respaldo antes de rendirse.

Audio

7. Fuentes remotas: HTML, YouTube, EPUB, ZIP y data URIs

Además de archivos locales, MarkItDown trabaja con fuentes remotas y contenedores. Esto es lo que abre la puerta a pipelines que ingieren documentación web o vídeos sin escribir un scraper propio.

El ZIP es un sumidero de documentos

El soporte de ZIP merece un párrafo aparte: en vez de devolver un binario ilegible, recorre el contenido del archivo y convierte lo que encuentra dentro. Para un corpus que llega comprimido —un lote de facturas, un export de correo, una carpeta de documentación— eso significa que un solo convert() puede producir Markdown de N documentos.

Ejemplo: convertir una página web

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://ejemplo.com/documentacion")
print(result.markdown)

Y por la CLI, igual de simple: markitdown https://ejemplo.com/documentacion -o doc.md. Para vídeos: markitdown "https://www.youtube.com/watch?v=..." -o transcripcion.md, siempre con el extra [youtube-transcription] instalado.

8. markitdown-mcp: documentos para tus agentes

El paquete markitdown-mcp expone la capacidad de conversión como un servidor MCP (Model Context Protocol) que un agente puede llamar. Es la forma de que tu asistente lea documentos en lugar de que tú le pegues el texto.

pip install markitdown-mcp

Expone una sola herramienta: convert_to_markdown(uri), donde la URI puede ser http:, https:, file: o data:.

Transportes

La ayuda real del comando instalado, ejecutada durante la preparación de este curso, es:

$ markitdown-mcp --help
usage: markitdown-mcp [-h] [--http] [--sse] [--host HOST] [--port PORT]

Run a MarkItDown MCP server

options:
  -h, --help   show this help message and exit
  --http       Run the server with Streamable HTTP and SSE transport rather
               than STDIO (default: False)
  --sse        (Deprecated) An alias for --http (default: False)
  --host HOST  Host to bind to (default: 127.0.0.1)
  --port PORT  Port to listen on (default: 3001)

El valor por defecto de --host es 127.0.0.1 y el de --port es 3001. Y atención: --sse está obsoleto, es un alias de --http.

Conectarlo a Claude Desktop

La recomendación oficial es usar la imagen Docker cuando el servidor se lanza desde Claude Desktop. En claude_desktop_config.json:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    }
  }
}

Y si además quieres dar acceso a una carpeta local, se monta el directorio:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/home/usuario/datos:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

Con el volumen montado, un archivo ejemplo.txt en /home/usuario/datos es accesible dentro del contenedor como /workdir/ejemplo.txt.

Ejecución en Docker

docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest
docker run -it --rm -v /home/usuario/datos:/workdir markitdown-mcp:latest

Depurarlo con MCP Inspector

npx @modelcontextprotocol/inspector

En el inspector (por defecto en http://localhost:5173/): elige STDIO y escribe markitdown-mcp como comando, o bien Streamable HTTP con http://127.0.0.1:3001/mcp, o SSE con http://127.0.0.1:3001/sse. Después: pestaña Tools → List Tools → convert_to_markdown → ejecútala sobre cualquier URI válida.

9. Plugins: markitdown-ocr y cómo escribir el tuyo

MarkItDown admite plugins de terceros, y esto resuelve un dilema de diseño del proyecto: añadir un formato nuevo suele implicar una dependencia nueva, y el equipo es conservador con eso. La respuesta son los plugins: el soporte de un formato nuevo se puede publicar e instalar de forma independiente del repositorio principal.

Los plugins están deshabilitados por defecto. El ciclo de trabajo es:

# Ver qué hay instalado
markitdown --list-plugins

# Convertir con plugins habilitados
markitdown --use-plugins ruta-al-archivo.pdf

markitdown-ocr: OCR con LLM Vision, sin dependencias nuevas

El plugin de referencia añade soporte OCR a los conversores de PDF, DOCX, PPTX y XLSX, extrayendo el texto de las imágenes incrustadas mediante LLM Vision. El detalle elegante: reutiliza el mismo patrón llm_client / llm_model que MarkItDown ya usa para las descripciones de imágenes, así que no introduce librerías de ML ni dependencias binarias.

pip install markitdown-ocr
pip install openai  # o cualquier cliente compatible con OpenAI

Uso, pasando el mismo cliente y modelo que usarías para describir imágenes:

from markitdown import MarkItDown
from openai import OpenAI

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

Y un comportamiento que hay que conocer bien: si no se proporciona llm_client, el plugin se carga igual, pero el OCR se omite silenciosamente y se usa el conversor integrado estándar. Es decir, un pipeline mal configurado no falla: simplemente pierde texto sin avisar.

Escribir tu propio plugin

El punto de partida oficial es packages/markitdown-sample-plugin, dentro del propio repositorio. Los pasos:

10. Azure y un pipeline RAG de principio a fin

La conversión offline cubre la mayoría de los casos, pero hay tres escenarios donde la nube gana: documentos escaneados o con tablas complejas, extracción de campos estructurados y tratamiento de audio y vídeo. MarkItDown ofrece dos integraciones de Azure.

Azure Document Intelligence

markitdown ruta.pdf -o documento.md -d -e "<document_intelligence_endpoint>"

El endpoint se puede fijar una sola vez en el entorno, de modo que después baste -d:

export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown ruta.pdf -o documento.md -d

Y en Python: md = MarkItDown(docintel_endpoint="<endpoint>"), seguido de md.convert("test.pdf").

Azure Content Understanding

Content Understanding va un paso más allá: extracción con campos estructurados en front matter YAML, soporte multimodal (documentos, imágenes, audio y vídeo) y analizadores configurables.

pip install 'markitdown[az-content-understanding]'

# CLI
markitdown ruta.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

# o fijando el endpoint en el entorno
export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown ruta.pdf --use-cu

En Python, con configuración cero y selección automática de analizador por tipo de archivo:

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("informe.pdf")    # documentos -> prebuilt-documentSearch
result = md.convert("reunion.mp4")    # vídeo      -> prebuilt-videoSearch
result = md.convert("llamada.wav")    # audio      -> prebuilt-audioSearch
print(result.markdown)

Con un analizador propio para extraer campos de dominio, la salida incluye el front matter:

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="mi-analizador-de-facturas",
)
result = md.convert("factura.pdf")
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->

Cuando se fija cu_analyzer_id, el conversor acota automáticamente el analizador a los tipos de archivo compatibles según su modalidad. Los tipos incompatibles —por ejemplo audio con un analizador de documentos— se enrutan a los analizadores predefinidos por defecto.

Comparativa de las tres vías

Para controlar el gasto, cu_file_types restringe qué formatos se enrutan a Content Understanding:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # solo los PDF usan CU
)

Pipeline completo: de una carpeta de documentos a contexto para el LLM

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
entrada, salida = Path("documentos"), Path("markdown")
salida.mkdir(exist_ok=True)

for f in entrada.rglob("*"):
    if f.is_dir():
        continue
    try:
        result = md.convert_local(str(f))
        destino = salida / (f.stem + ".md")
        # conservamos el origen como encabezado: contexto que el LLM no puede adivinar
        destino.write_text(f"# {f.name}\n\n{result.markdown}", encoding="utf-8")
        print("ok  ", f.name)
    except Exception as e:
        print("fallo", f.name, type(e).__name__)

Y la variante en contenedor, útil para pipelines reproducibles y sin ensuciar el entorno del host:

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