A MarkItDown suelen meterlo en el mismo saco que los web scrapers, pero eso no cuadra. No tiene crawler, no ejecuta JavaScript y no sirve para coger una URL y limpiarle el contenido accesorio. Lo que hace es tomar bytes que ya tienes —un PDF, un documento de Word, una hoja de cálculo, una presentación— y convertirlos en Markdown para que un modelo de lenguaje pueda leerlos.
Pasé un par de semanas probando el MarkItDown de Microsoft con documentos reales en un único Mac, evaluando cada tabla frente a un manifiesto que preparé antes de la ejecución y cronometrando cada conversión. Resumen rápido: con entradas limpias es rápido y fiel, su empaquetado oculta un runtime de machine learning de 73 MB que no pediste, y sus tablas se rompen de formas que pasan un chequeo de “¿sobrevivió el texto?” pero fallan uno de “¿está cada dato en su columna correcta?”. Aquí tienes el panorama completo, con números.
Qué es realmente MarkItDown
MarkItDown es una utilidad en Python de Microsoft que convierte archivos y documentos de Office en Markdown optimizado para LLMs. Si le pasas un PDF, un .docx, un .xlsx, un .pptx, una imagen, un archivo HTML o algunos otros formatos, te devuelve Markdown. Se puede usar de tres formas: con CLI (markitdown file.pdf -o out.md, o leyendo desde stdin), con API de Python (MarkItDown().convert(...)) y con un servidor MCP opcional para flujos de trabajo con agentes.
La clave de todo esto es lo que no hace, porque ni el README lo promete ni mis pruebas lo encontraron: no rastrea enlaces, no renderiza JS, no sigue páginas enlazadas, no pagina y no extrae solo el contenido principal al estilo readability. Es un convertidor de documentos completos. Tú aportas los bytes; él los normaliza. Esa diferencia decide si esta herramienta encaja o no en tu stack, así que volveré a ella varias veces.
El repositorio, en métricas de GitHub, es un peso pesado: 165.282 estrellas y 11.790 forks a mediados de julio de 2026, licencia MIT y la versión más reciente (v0.1.6) publicada el 2026-05-26. Eso sí, ese número de estrellas refleja el entusiasmo general por las herramientas para LLM del repositorio de Microsoft, no necesariamente la madurez interna del convertidor. También hay 833 issues abiertos, y varios te conviene mirarlos antes de instalarlo (más abajo).
HTML a Markdown: rápido, completo y con el boilerplate incluido
Como el resto de mi serie de reseñas sobre scrapers usa los mismos cuatro fixtures web, le pasé a MarkItDown exactamente esos mismos HTML locales —no para evaluarlo como scraper, sino para ver qué tal convierte HTML a Markdown. En páginas bien estructuradas, lo hace de verdad bien.
Las cuatro páginas se convirtieron con la instalación base, sin extras, y todas conservaron el contenido principal. El artículo de Wikipedia sobre "Web scraping" (226 KB) mantuvo su árbol de encabezados —un h1, siete h2 y doce h3, coincidiendo con la estructura real del artículo— y conservó 418 enlaces como [texto](url) correctos. La tabla de estadísticas de hockey 26×9 de la página Scrape This Site forms quedó como una tabla GFM limpia de 27 filas (encabezado + separador + 26 filas de datos), incluidos los campos vacíos. La velocidad tampoco fue un problema: mediana de 48 ms para la página pequeña de citas hasta 352 ms para la página de Wikipedia de 226 KB.
Pero aquí está el detalle, y no es un bug sino una decisión de diseño. MarkItDown no elimina el boilerplate. Convierte todo el <body>, así que el “chrome” del sitio también viaja en la salida, y ese residuo crece según cuánto chrome tenga la página.
| Página | Caracteres de salida | Encabezados (h1/h2/h3) | Enlaces | Líneas de chrome del sitio |
|---|---|---|---|---|
| Books to Scrape | 10,478 | 1 / 0 / 0 | 94 | 0.6% (1/159) |
| Quotes to Scrape | 2,973 | 1 / 1 / 0 | 55 | 1.2% (1/86) |
| ScrapeThisSite forms | 3,385 | 1 / 0 / 0 | 31 | 6.7% (5/75) |
| Wikipedia Web scraping | 60,159 | 1 / 7 / 12 | 418 | 12.4% (42/338) |
En la página de Books, casi sin chrome, solo el 0,6% de las líneas de salida es chrome. En Wikipedia, sube al 12,4%: 42 de 338 líneas no vacías son cosas como “jump to content”, “toggle the table of contents”, “22 languages”, “retrieved from”, y pies de cookie/licencia. Esos banners de mantenimiento de Wikipedia (“This article needs additional citations”) incluso se renderizan fielmente como tablas de dos columnas, y por eso aparecen nueve filas de tabla en una página que no tiene una tabla de datos real.
Nada de eso significa que MarkItDown lo esté haciendo mal. Es un convertidor de documento completo, no un extractor de readability: convertir HTML a Markdown de forma fiel no es lo mismo que extraer solo el artículo limpio. Trafilatura y herramientas tipo Firecrawl intentan devolver solo el contenido principal; MarkItDown devuelve la página. Por debajo, su _html_converter.py elimina <script> y <style> y luego pasa todo el body a la librería markdownify —sin ninguna heurística de contenido principal. Si solo quieres el artículo, esta no es la capa adecuada.
Su terreno natural: PDF, DOCX, XLSX y PPTX
Los documentos son para lo que MarkItDown fue creado. Lo probé con archivos públicos reales: un paper de arXiv con capa de texto, el whitepaper de Bitcoin, un PDF escaneado solo con imagen al que le quité todo el texto, y los archivos DOCX/XLSX/PPTX del propio conjunto de pruebas de MarkItDown (con UUIDs semilla para detectar pérdidas silenciosas de contenido).
| Documento | Entrada | Caracteres de salida | Probes | Tiempo mediano | Notas |
|---|---|---|---|---|---|
| arXiv 1706.03762 (PDF con capa de texto) | 2.2 MB | 40,174 | 7/7 | 3.7 s (warm) | título, "Transformer", "BLEU", "References" presentes |
| Whitepaper de Bitcoin (PDF de 9 págs.) | 184 KB | 22,485 | 6/6 | 1.4 s | "Satoshi Nakamoto", "proof-of-work", "Conclusion" presentes |
| PDF escaneado (sin capa de texto) | 89 KB | 0 | 0/4 | 15 ms | salida vacía, sin error, sin OCR |
| DOCX (test.docx) | 136 KB | 4,651 | — | 70 ms | encabezados + tabla GFM; los UUID incrustados sobreviven |
| DOCX con ecuaciones | 15 KB | 240 | — | 101 ms | Office Math preservado como LaTeX |
| XLSX (test.xlsx) | 12 KB | 808 | — | 57 ms | cada hoja → ## SheetName + tabla GFM |
| PPTX (test.pptx) | 278 KB | 2,047 | — | 52 ms | marcadores de número de diapositiva, tablas y gráfico → tabla |
La recuperación de texto en los PDFs con capa de texto fue excelente: 7 de 7 probes predefinidos en el paper de arXiv “Attention Is All You Need” y 6 de 6 en el whitepaper de Bitcoin. Y ninguno de los archivos de Office perdió un solo UUID centinela, así que no hubo pérdida silenciosa de contenido en los fixtures de regresión de los mantenedores. Un buen triunfo concreto: la ruta de DOCX (vía mammoth) conserva ecuaciones de Office Math como LaTeX, convirtiendo equations.docx en matemáticas reales $$...$$. Si le das documentos de Word cargados de fórmulas a un LLM, eso es una ventaja real, aunque bastante específica, que no vi documentada por ahí.
Hay dos hallazgos en este terreno que merecen atención propia, porque son los más propensos a hacerte tropezar.
El PDF escaneado que desaparece
Si le das a MarkItDown un PDF solo de imagen, sin capa de texto, devuelve una cadena vacía. Cero caracteres, sin excepción, sin aviso: convertido en unos 15 ms porque no hay nada que extraer. La ruta PDF de MarkItDown es solo extracción de texto (por debajo usa pdfminer y pdfplumber) y no incluye OCR en la instalación base ni en ningún extra de pip.
Eso importa mucho por lotes. Si un desarrollador procesa una carpeta de PDFs donde algunos son escaneos, esos archivos se convierten en resultados vacíos sin ninguna señal de que se saltó algo. Verifiqué que el fixture no estuviera roto ejecutando extract_text de pdfminer directamente: cero caracteres, sin capa de texto, confirmado. Así que la salida vacía es el comportamiento real de MarkItDown ante un escaneo real. Esto reproduce una laguna de OCR fallback (#1268) que lleva tiempo abierta y rastreada upstream. La vía documentada es usar el backend opcional Azure Document Intelligence o un plugin; ninguno viene en la instalación por defecto.
Los PDFs salen como texto plano, no como estructura
En ambos PDFs con capa de texto, MarkItDown produjo cero marcadores de encabezado Markdown. Un PDF no trae etiquetas semánticas de encabezado, y MarkItDown no las infiere por tamaño de fuente, así que cada línea acaba al nivel del cuerpo. La recuperación de texto es alta; la estructura, plana.
Y esto no es solo mi resultado. Benchmarks públicos de terceros puntúan la jerarquía de encabezados PDF de MarkItDown alrededor de 0.0 y la fidelidad de tablas en torno a 0.27, muy por debajo de la 0.88 de Docling con TableFormer (véase la comparación MarkItDown vs Docling vs Marker y el benchmark READoc). Mis fixtures reproducen esos resultados, lo cual fortalece la evidencia: mis números coinciden con una fuente externa. El intercambio que reportan esos mismos benchmarks es que MarkItDown corre aproximadamente 100 veces más rápido que Docling, algo que encaja con mis tiempos de segundos y no minutos en documentos que una herramienta con modelo de layout tarda minutos en procesar. La conclusión: MarkItDown te da texto de PDF limpio y rápido; no te da la estructura del PDF. Si los encabezados y las tablas deben sobrevivir, la capa correcta es una herramienta de modelos de layout como Docling o Marker.
Tablas: el contenido siempre sobrevive, la estructura no siempre
Las tablas son donde “¿sobrevivió el texto?” y “¿sigue siendo usable el dato?” se separan, así que monté una matriz de 13 casos —una <table> por caso, cada una evaluada contra un manifiesto escrito antes de la ejecución— para mapear exactamente qué formas aguantan y cuáles se rompen.
Lo importante: MarkItDown no perdió nunca el contenido de las tablas. Los 13 casos conservaron el 100% de los tokens registrados. Pero la fidelidad estructural se dividió en tres grupos. Siete de trece produjeron una rejilla GFM bien formada (simple, header-colspan, 24 columnas de ancho, sin encabezado, celdas vacías, bloque dentro de celda y árabe de derecha a izquierda). Cuatro quedaron irregulares, porque Markdown no entiende celdas combinadas, así que rowspan, colspan y fuentes mal formadas generan filas cortas. Y dos quedaron directamente rotas.
Vale la pena nombrar esas dos roturas. Una tabla anidada (un <table> dentro de un <td>) se aplana en línea, volcando sus propias barras | y su fila separadora dentro de la celda padre y produciendo una fila basura de 14 “columnas”. Y un | literal dentro de una celda no se escapa —el texto a | b se convierte en dos columnas, x || y en tres—, así que una tabla de dos columnas termina emitiendo filas de dos, tres y cuatro columnas, y cualquier parser Markdown posterior leerá límites equivocados. Curiosamente, los asteriscos y backticks dentro de celdas sí se escapan; las barras no. La causa es que la ruta HTML de MarkItDown usa el manejo de tablas por defecto de markdownify, y su subclase personalizada sobreescribe enlaces, imágenes y encabezados, pero no las celdas de tabla. La misma clase de bug de escape de barras es un issue abierto para el convertidor CSV (#2019), aunque ese arreglo no toca la ruta HTML que yo probé.
La parte más sutil —y la que más me gustaría que viera un ingeniero de datos— es rowspan. El caso t03 no solo queda irregular; desalineó datos en silencio. Una etiqueta con rowspan=2 (“Fruit”) se emite una sola vez, y la fila de debajo queda como una fila corta de dos columnas (| Banana | 8 |), así que “Banana” cae bajo la columna Group en lugar de Item. Todos los tokens están ahí. Un consumidor ingenuo que lea la segunda columna obtendrá el valor equivocado. Ese es el tipo de error que pasa un chequeo de supervivencia de texto y corrompe un dataset sin hacer ruido.
La limitación de spans en sí es una restricción de diseño conocida y rastreada (#1211, #1248): una rejilla plana GFM de pipes no puede representar spans ni anidamiento, así que el convertidor intercambia estructura por completitud del contenido. También hay comportamientos buenos: las tablas sin encabezado reciben una fila de encabezado vacía sintetizada (así ningún dato se promociona silenciosamente a encabezado), las celdas vacías se preservan y <caption> sobrevive como línea de texto encima de la tabla.
Instalación y arranque: el peaje que una “utilidad ligera” no te avisa que existe
Aquí nada me sorprendió más, y es donde el encuadre de “utilidad ligera en Python” promete más de la cuenta en silencio.
Primero: no ejecutes pip install 'markitdown[all]'. En Python 3.14, hace backtracking sin avisar hasta markitdown 0.0.2, una versión de hace dos años; lo reproduje en vivo en un venv limpio. Al fijar la versión se ve por qué: pip install 'markitdown[all]==0.1.6' falla porque el extra [all] fija youtube-transcript-api~=1.0.0, y en PyPI actual cada build de ese rango está restringida a Python <3.14, mientras que las únicas compatibles con 3.14 quedan fuera de ese pin. Así que el resolver retrocede hasta la última versión cuyas dependencias sí puede satisfacer. Esto coincide con un issue abierto upstream (#2179). La solución es simple: fija la versión e instala los extras por separado: pip install 'markitdown==0.1.6' y luego pip install 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Cada uno resuelve bien; solo el paquete combinado [all] arrastra el pin problemático. (Esta trampa depende de la versión de Python: en Python 3.13 o anterior, la restricción puede no afectar, así que [all] podría resolverse de otra manera.)
Segundo: la huella. La instalación base pesa 161 MB (un venv vacío de 13 MB más 148 MB). De eso, onnxruntime (73 MB) y numpy (34 MB) suman 107 MB —el 66% de toda la huella base—, y ambos entran por una sola dependencia obligatoria: magika, el detector de tipos de archivo con ML de Google. O sea: un convertidor de texto trae un runtime ONNX de inferencia de 73 MB en la instalación base, antes de añadir un solo extra de documentos. Si añades los extras de documentos, el venv llega a 310 MB. Sigue siendo mucho más ligero que una pila con navegador headless, pero si esperabas una utilidad de “instalar y listo” de tamaño micro, conviene saber que un runtime ONNX viene incluido.
Tercero —y este es el hallazgo de todo el paquete que supera todas las pruebas de novedad que hice—: incluso tras una instalación limpia, import markitdown cuesta unos 3,35 segundos en esta máquina. El coste está casi entero en el momento de importación: markitdown._markitdown importa de forma ansiosa todo el registro de convertidores (2,56 s acumulados, 76% del total), lo que arrastra pandas (594 ms, vía el convertidor XLSX), python-pptx (427 ms), magika (354 ms) y requests (270 ms), conviertas o no alguno de esos formatos. En un servicio de larga duración ese coste se amortiza y da igual. En una invocación CLI o en un cold start serverless, es un peaje real por proceso que la etiqueta de “utilidad ligera” no te hace esperar. (Matiz justo: esta fue una única ejecución perfilada, tratada como una observación, no como una distribución de múltiples runs.)
Escala: no se rompe, pero reserva CPU para PDFs y RAM para hojas de cálculo
Empujé cuatro casos grandes por separado, cada uno en su propio proceso para que el pico de memoria no quedara contaminado por una ejecución previa. Nada se cayó. Pero el perfil de coste está muy descompensado.
| Caso | Entrada | Caracteres de salida | Tiempo mediano | Δ RSS pico |
|---|---|---|---|---|
| NIST SP 800-53r5 (PDF de 492 páginas) | 5.9 MB | 1,625,365 | 192.5 s | +40 MB |
| XLSX 50,000 filas × 8 columnas | 2.1 MB | 3,722,955 | 62.1 s | +374 MB |
| arXiv 1706.03762 (~15 páginas) | 2.2 MB | 40,174 | 12.6 s | +25 MB |
| XLSX 200 filas × 64 columnas | 46 KB | 120,129 | 2.9 s | +22 MB |
El PDF NIST de 492 páginas tardó una mediana de 192,5 segundos —unos 3,2 minutos, o 0,39 s por página— porque pdfplumber ejecuta detección de formularios basada en la posición de las palabras en cada página. El RSS pico se quedó en +40 MB, así que el cuello de botella es CPU, no memoria. Incluso el PDF de arXiv de 15 páginas tardó 12,6 segundos en su propio proceso aislado, unas 3,4 veces los 3,7 segundos que mostró ese mismo archivo en caliente dentro de mi suite documental. Esa diferencia es el coste del proceso en frío, y confirma que el trabajo por página es lo que manda, no el tamaño bruto del archivo. Si quieres un único número transferible para ese PDF, usa los 12,6 s aislados.
La ruta de hojas de cálculo invierte el cuello de botella. Un XLSX de 2,1 MB y 50.000 filas se disparó hasta +374 MB de RSS pico (y 3,7 millones de caracteres de salida) porque el convertidor carga toda la hoja y construye un único string Markdown enorme. La recomendación práctica es directa: para PDFs grandes, reserva minutos de CPU; para hojas de cálculo grandes, reserva cientos de MB de RAM. Estos números son de una sola máquina en macOS arm64 y Python 3.14, y las constantes por página y por fila dependen de la plataforma; pero la forma general —PDF lento y ligado a CPU, XLSX pesado en memoria, sin caídas— sí se traslada.
Dónde encaja Thunderbit —y dónde no
Prueba Thunderbit para extraer datos web
Esta es la comparación en la que sería fácil pasarse de la raya, así que la delimito con cuidado. MarkItDown y Thunderbit resuelven problemas vecinos, no el mismo.
MarkItDown convierte archivos que ya tienes. Thunderbit obtiene primero la página. El endpoint /distill de Thunderbit convierte una página web viva en Markdown limpio, listo para LLMs —manejando el renderizado JS, anti-bot y contenido dinámico para lo que MarkItDown no tiene maquinaria—, y su endpoint /extract devuelve JSON estructurado que coincide con un esquema, no solo Markdown crudo. Para desarrolladores, eso está expuesto como API (POST /distill / POST /extract), servidor MCP y CLI (npx @thunderbit/thunderbit-cli) sobre un único motor de IA, el mismo que impulsa la extensión con más de 100.000 usuarios.
Así que solo coinciden en una cosa: ambos pueden emitir “Markdown listo para LLM”. Pero el dominio de entrada es distinto: distill de Thunderbit toma una URL en la web abierta, mientras que MarkItDown toma un archivo local. No son equivalentes intercambiables, y no voy a fingir lo contrario. La pila realista usa ambos: capturas y rastreas la web con Thunderbit (o un servicio tipo Firecrawl), y luego normalizas los documentos locales mezclados que también tengas —PDFs, decks y hojas de cálculo— con MarkItDown. Uno se encarga de la red; el otro, del archivador.
Pros y contras
Puntos fuertes
- Recuperación completa del cuerpo en HTML limpio (4/4 páginas), preservando con fidelidad árboles de encabezados y enlaces
- Alta recuperación de texto en PDF/DOCX (arXiv 7/7 probes, Bitcoin 6/6) y sin pérdida silenciosa de contenido en los fixtures Office de los mantenedores
- Las ecuaciones de Office Math se conservan como LaTeX: una ventaja real en un nicho muy concreto
- No se cayó en ningún caso de escala, incluso con un PDF de 492 páginas y un XLSX de 50k filas
- Muy fácil de invocar: CLI,
convert(), piping por stdin y servidor MCP opcional - Licencia MIT, mantenido activamente por Microsoft, issue tracker receptivo
Puntos débiles
- Conserva el boilerplate: hasta 12,4% de líneas de chrome en Wikipedia; no es un extractor de artículos
- Las tablas se rompen con spans, anidamiento y pipes dentro de celdas (2/13 rotas, 4/13 irregulares), y rowspan puede desalinear datos en silencio
- Los PDFs escaneados o solo imagen devuelven salida vacía, sin OCR y sin error
- La salida de PDF no tiene estructura de encabezados (coincide con los benchmarks públicos)
- Instalación base de 161 MB con un runtime ONNX de 73 MB; ~3,35 s de import en frío
- El extra
[all]hace backtracking en silencio hasta una vieja 0.0.2 en Python 3.14
Quién debería usarlo y quién no
Usa MarkItDown si quieres estandarizar un montón de documentos locales mixtos —Word, Excel, PowerPoint, PDFs con capa de texto— a Markdown para una canalización con LLM, y te importa más el texto completo que la estructura preservada. Como convertidor de última milla en un job por lotes, para alimentar texto limpio a un modelo, es rápido, fiel y gratuito.
Evítalo, o combínalo con otra herramienta, si tu tarea es cualquiera de estas: solo necesitas el artículo principal de una página web (usa una herramienta tipo readability o Firecrawl); necesitas que los encabezados y las tablas de un PDF sobrevivan intactos (eso es terreno de Docling o Marker); o tus entradas incluyen documentos escaneados que requieren OCR (necesitarás el backend de Azure u otra herramienta distinta). Y si pensabas comprar un scraper —algo que obtenga y rastree páginas—, esto no es eso en absoluto.
La puntuación provisional que hice con una rúbrica pensada para scrapers deja a MarkItDown en 60/100, y ese total bajo es un artefacto de evaluar un convertidor con un examen para crawlers. En su propio terreno, sus métricas de fidelidad de texto son altas; sus debilidades están en lo estructural (tablas, encabezados de PDF) y en el empaquetado (huella, importación, la trampa de [all]), no en la calidad del texto. Júzgalo por lo que es —un convertidor de archivos a Markdown— y verás una herramienta sólida, bien mantenida y con algunos bordes afilados que conviene conocer antes de llevarla a producción.
Preguntas frecuentes
¿MarkItDown es un web scraper?
No. No tiene crawler, no renderiza JavaScript, no sigue enlaces y no pagina. Convierte archivos y documentos que ya tienes —PDF, DOCX, XLSX, PPTX, imágenes, HTML— a Markdown. Si necesitas obtener y rastrear páginas web en vivo, te conviene una herramienta de scraping como Thunderbit o Firecrawl; MarkItDown es el paso que viene después, convirtiendo archivos locales o ya obtenidos en Markdown limpio.
¿Por qué pip install markitdown[all] instala una versión antigua?
En Python 3.14, el extra [all] fija youtube-transcript-api~=1.0.0, y todas las builds de ese rango están limitadas a versiones de Python inferiores a 3.14. El resolver no puede satisfacer ese pin, así que retrocede en silencio a markitdown 0.0.2, una versión de hace dos años. La solución es fijar la versión e instalar los extras por separado: pip install 'markitdown==0.1.6' y luego añadir 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Esto se sigue en el issue #2179.
¿MarkItDown hace OCR en PDFs escaneados?
No en la instalación por defecto. Su ruta PDF solo extrae texto, así que un PDF solo de imagen, sin capa de texto, devuelve una cadena vacía —sin error, sin aviso. El OCR requiere el backend opcional Azure Document Intelligence o un plugin, ninguno incluido por defecto. Es una laguna conocida y con seguimiento de largo plazo (issue #1268).
¿Qué tal maneja MarkItDown las tablas?
En cuanto al contenido, muy bien: en mi prueba de 13 casos conservó el 100% del contenido de tabla en todos los casos. Estructuralmente, depende de la forma: las tablas simples, anchas, sin encabezado y con celdas vacías salen como rejillas GFM limpias, pero rowspan y colspan se vuelven irregulares (y rowspan puede desalinear datos en silencio hacia la columna equivocada), las tablas anidadas se aplastan en filas basura y los caracteres | literales dentro de celdas no se escapan. El formato plano de tabla de Markdown simplemente no puede representar spans ni anidamiento.
¿MarkItDown es lo bastante rápido para documentos grandes?
No se cae con archivos grandes, pero hay que presupuestar recursos según el tipo. Un PDF de 492 páginas tardó unos 3,2 minutos (aprox. 0,39 s/página) porque hace detección de formularios por página, y eso lo convierte en una carga de CPU. Una hoja de cálculo de 50.000 filas tardó cerca de un minuto, pero usó +374 MB de RAM porque construye un string Markdown enorme en memoria. Para PDFs grandes, piensa en minutos de CPU; para hojas de cálculo grandes, en cientos de MB de RAM.
Prueba Thunderbit para extraer datos web Get Started Free
