Tutorial de Microsoft MarkItDown: convertir documentos a Markdown para crear bases de conocimiento con IA

microsoft/markitdown de Microsoft es una herramienta de Python para convertir muchos tipos de archivos a Markdown. Su objetivo no es conservar el diseño con alta fidelidad, sino transformar documentos, hojas de cálculo, páginas web, imágenes, audio y otros materiales en Markdown más fácil de usar en flujos con LLM, RAG, índices de búsqueda y procesamiento de texto.

Repositorio del proyecto:

https://github.com/microsoft/markitdown

Si necesitas enviar a un modelo de IA PDFs, archivos de Word, hojas de Excel, presentaciones de PowerPoint, páginas web, imágenes o archivos comprimidos para analizarlos, MarkItDown encaja bien como paso de preprocesamiento. Su salida es Markdown en texto plano, más fácil de depurar, dividir, buscar y archivar que los archivos binarios originales.

Qué soporta MarkItDown

Según el README oficial, MarkItDown soporta tipos de entrada como:

• PDF
• PowerPoint
• Word
• Excel
• Imágenes, incluyendo metadatos EXIF y OCR
• Audio, incluyendo metadatos EXIF y transcripción de voz
• HTML
• CSV, JSON, XML
• Archivos ZIP, recorriendo su contenido
• URLs de YouTube
• EPUB

Su enfoque es claro: convertir archivos a Markdown para usarlos después en flujos con LLM y procesamiento de texto. No conviene tratarlo como un conversor que conserva estrictamente el diseño. Para currículos, contratos, documentos escaneados, materiales de producto, grabaciones de reuniones o capturas de páginas web, lo importante normalmente no es reproducir cada píxel, sino extraer una estructura textual que el modelo pueda entender de forma estable.

Comandos de instalación

La forma más sencilla de instalarlo es usar pip:

1

pip install markitdown

Si necesitas todas las funciones opcionales, instala el extra all:

1

pip install 'markitdown[all]'

Si solo necesitas formatos concretos, puedes instalar extras específicos. Por ejemplo, PDF, DOCX y PPTX:

1

pip install 'markitdown[pdf,docx,pptx]'

Para instalar desde el código fuente:

1
2
3

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

Uso en línea de comandos

Después de instalarlo, puedes usar directamente el comando markitdown. El uso más básico convierte un archivo a la salida estándar:

1

markitdown path-to-file.pdf

Guardar el resultado como un archivo Markdown:

1

markitdown path-to-file.pdf -o output.md

Convertir documentos de Office:

1
2
3

markitdown report.docx -o report.md
markitdown slides.pptx -o slides.md
markitdown data.xlsx -o data.md

Convertir una página web:

1

markitdown https://example.com -o page.md

Convertir una URL de YouTube:

1

markitdown https://www.youtube.com/watch?v=VIDEO_ID -o video.md

Procesar un archivo ZIP:

1

markitdown archive.zip -o archive.md

Estos comandos son útiles para validar primero el resultado a mano. Cuando la estructura de salida sea la esperada, puedes poner MarkItDown en scripts de automatización, flujos de importación a una base de conocimiento o un RAG pipeline.

Uso de la API de Python

MarkItDown también se puede usar como biblioteca de Python. El README oficial muestra el patrón básico: crear una instancia de MarkItDown y llamar a convert:

1
2
3
4
5

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

Si quieres conectar un cliente de OpenAI para describir imágenes, puedes pasar el cliente a MarkItDown:

1
2
3
4
5
6
7

from openai import OpenAI
from markitdown import MarkItDown

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

Esta capacidad sirve para materiales basados en imágenes, como capturas de pantalla, imágenes escaneadas o páginas con gráficos. En uso real, conviene vigilar coste, privacidad y llamadas de red, especialmente al procesar documentos internos.

Uso con Docker

Si no quieres modificar tu entorno local de Python, puedes ejecutarlo con Docker. El README oficial ofrece este comando para construir la imagen:

1

docker build -t markitdown:latest .

Luego monta el directorio actual en el contenedor y ejecuta la conversión:

1

docker run --rm -v .:/workdir markitdown:latest path-to-file.pdf -o output.md

Este enfoque encaja bien en servidores, CI o procesamiento temporal por lotes. La desventaja es que depurar dependencias puede ser un poco más lento que en un entorno local de Python.

Sistema de plugins

MarkItDown soporta plugins, pero los plugins de terceros no se activan por defecto. Ver plugins:

1

markitdown --list-plugins

Activar plugins:

1

markitdown --use-plugins path-to-file.foo -o output.md

Activar plugins en Python:

1
2
3
4
5

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("example.foo")
print(result.text_content)

Los plugins son útiles para ampliar formatos privados, formatos internos de documentos o archivos exportados por sistemas empresariales concretos. Ten en cuenta que los plugins ejecutan código adicional, así que no conviene activarlos si la fuente no es confiable.

Dónde encaja mejor

Yo usaría MarkItDown en escenarios como estos:

1. Convertir PDF, DOCX, PPTX y XLSX a Markdown antes de importarlos a una base de conocimiento.
2. Convertir páginas web, YouTube y EPUB en texto que se pueda buscar.
3. Preprocesar documentos antes de RAG para obtener Markdown más fácil de dividir en fragmentos.
4. Enviar materiales convertidos a Codex, Claude Code, Cursor u otras herramientas similares para que los lean.
5. Ordenar documentos históricos por lotes y generar un formato intermedio .md unificado.

Un flujo simple puede ser:

1
2

mkdir -p markdown
markitdown input.pdf -o markdown/input.md

Para procesamiento por lotes, puedes enumerar archivos con un script y llamar a markitdown para cada uno. Después de convertir, conviene revisar manualmente varias salidas, sobre todo tablas, documentos escaneados, PDFs con diseño complejo y archivos con varias columnas.

Límites de uso

MarkItDown es útil, pero hay algunos límites que conviene recordar:

1. El orden de lectura de PDFs complejos puede no ser perfecto, especialmente con varias columnas, notas al pie, encabezados y pies de página.
2. OCR y descripciones de imágenes dependen de componentes adicionales o LLMs, por lo que calidad y coste deben evaluarse por separado.
3. Markdown es bueno para expresar estructura textual, pero no para conservar diseño exacto.
4. Al procesar archivos internos con plugins o LLMs, hay que cuidar la seguridad de los datos.
5. La salida convertida debería tratarse como un artefacto intermedio, no como un equivalente garantizado del archivo original.

Si el objetivo es que un modelo entienda tus materiales, MarkItDown va en la dirección correcta: primero convierte muchos tipos de archivos a Markdown, y después puedes limpiar, dividir, indexar y consultar. No es un conversor universal, pero como puerta de entrada documental para LLMs es claro, ligero y fácil de integrar en flujos de Python existentes.