La biblioteca HTML a Markdown más popular no convierte tablas

turndown fue la más destacada de las cuatro bibliotecas probadas en el momento de capturar los metadatos, con 11.386 estrellas en GitHub. En los cuatro archivos HTML compartidos, generó cero tablas Markdown con su configuración predeterminada y usó 24,6 % más tokens que markdownify para las mismas entradas.

Las cuatro recuperaron por completo todas las cadenas de prueba del contenido. Las diferencias están solo en cómo manejan la estructura y en cuánto te cuesta esa estructura más adelante.

Qué se midió y con qué archivos

Esta base de investigación ya incluía un paquete para markitdown con cinco archivos HTML y cadenas de prueba predefinidas: strings exactas que debían sobrevivir, además de cadenas de texto repetitivas para detectar elementos decorativos de la página. La comparación agregada usa los cuatro archivos compartidos por los cuatro convertidores: un catálogo de librería, un sitio de citas, una tabla de estadísticas de hockey y el artículo de Wikipedia sobre web scraping. Un quinto archivo, Nothing but tables, se usa solo como diagnóstico centrado en tablas y se excluye del agregado del 24,6 %.

Los cuatro son: turndown 7.2.4 (Node), markdownify 1.2.3, html2text 2025.4.15 y markitdown, cuyas filas publicadas se usan tal cual. Las páginas: un catálogo de librería, un sitio de citas, una tabla de estadísticas de hockey y el artículo de Wikipedia sobre web scraping.

Cada nombre de métrica a continuación coincide exactamente con el campo correspondiente del propio artefacto de markitdown, así que las filas pueden colocarse una junto a la otra sin que nadie tenga que reconciliar dos definiciones de la misma palabra.

La tabla

Cuatro archivos: los mismos que también ejecutó markitdown. Los números completos por archivo están en fiveway-scores.json. Los tokens se contaron con o200k_base; las filas de tabla de markitdown se volvieron a contar a partir de su propio Markdown almacenado, usando el mismo contador aplicado a los demás.

La supervivencia del contenido está empatada. Las dieciséis cadenas del cuerpo, repartidas entre los cuatro archivos, sobrevivieron en todos los convertidores. Si tu única pregunta es “¿el texto llega completo?”, cualquiera de los cuatro responde que sí.

La estructura no está empatada. En los cuatro archivos compartidos, markdownify y markitdown generan 36 filas de tabla Markdown; html2text genera 32; turndown no genera ninguna. En el diagnóstico aparte centrado solo en tablas, markdownify generó 62 filas y html2text 59; esas filas no se incluyen en el agregado anterior.

El coste en tokens es 24,6 % más alto en turndown, y la razón no son las tablas. Yo asumí que lo era, pero los números por archivo dicen otra cosa — mira abajo.

Qué le hace turndown a una tabla

Aquí está el archivo de estadísticas de hockey, las mismas filas, de tres maneras.

turndown:

Team Name

Year

Wins

Losses

Boston Bruins

1990

44

24

markdownify:

| Team Name | Year | Wins | Losses | ... |
| --- | --- | --- | --- | --- |
| Boston Bruins | 1990 | 44 | 24 | ... |

html2text:

Team Name  |  Year  |  Wins  |  Losses  | ...
---|---|---|---|---
Boston Bruins  |  1990  |  44  |  24  | ...

Cada valor sobrevive a la conversión de turndown, y por eso obtiene 16/16 en las pruebas. Lo que no sobrevive es a qué columna pertenece cada valor. Si lees la salida de turndown, 44 es solo un número en una línea; no puedes saber que corresponde a las victorias de Boston sin contar posiciones y esperar que ninguna celda esté vacía. En este archivo, algunas celdas sí están vacías, así que contar posiciones tampoco funciona.

Para un modelo que lea la salida, esa es la diferencia entre una tabla sobre la que puede responder preguntas y una lista de números que tendrá que adivinar.

No es exactamente un fallo, sino un límite documentado: el núcleo de turndown no maneja tablas, y turndown-plugin-gfm existe para añadir ese soporte. Pero la instalación por defecto no lo incluye, y 11.386 estrellas sugiere que mucha gente está usando la versión base.

De dónde sale realmente la diferencia de tokens

Escribí el párrafo anterior convencido de que la diferencia de 24,6 % en tokens venía de las tablas aplanadas apareciendo como caracteres. Luego lo revisé por archivo, y no es así.

En el archivo que es solo tablas, turndown es 22 % más barato — porque la estructura de barras verticales también cuesta tokens, y turndown no genera ninguna. Aplanar una tabla, por sí solo, no implica una penalización de tokens.

El archivo de Wikipedia representa el 74 % del total, y solo tiene nueve filas de tabla. Su diferencia de 15.378 caracteres no puede venir de las tablas. Viene de esto:

(function(){var className="client-js vector-feature-language-in-header-enabled…
.mw-parser-output cite.citation{font-style:inherit;word-wrap:break-word}…
(RLQ=window.RLQ||[]).push(function(){mw.config.set({"wgHostname":"mw-web…

turndown no elimina el contenido de <script> y <style>. markdownify y html2text sí lo hacen. Contado por marcadores que solo aparecen dentro de esos elementos: la salida de turndown incluye 10 marcadores de script y 84 de style a lo largo de los archivos; los otros dos no incluyen ninguno. En la página de Wikipedia, ocho líneas de JavaScript de configuración y CSS en línea de MediaWiki explican 14.644 caracteres — el 95 % de toda la diferencia (script-style-stripping.json).

Ese es el hallazgo que realmente me llevaría a actuar. Una tabla aplanada es un problema de estructura que puedes ver. Un bloque de configuración JavaScript dentro de tu Markdown es coste puro sin información alguna, y en una página real eclipsa todo lo demás de esta comparación.

html2text escribe tablas que quizá no reconozcas

html2text obtuvo 32 filas donde markdownify y markitdown marcaron 36, y la primera versión de mi contador le daba 1.

Eso era un problema de mi regla de conteo, no de la biblioteca. html2text emite Team Name | Year | Wins sin barras al inicio ni al final, una forma habitual de tabla Markdown, pero invisible para una regex que exige ^\|.*\|$. Yo había escrito esa regex, la había ejecutado y estaba listo para concluir que html2text no hacía tablas.

Sí las hace. El contador corregido usa una heurística: una secuencia de líneas consecutivas con barras verticales y una fila separadora dentro. Con esa regla, html2text pasa de 1 a 32. No es un analizador Markdown completo, así que las filas deben leerse como mediciones hechas bajo un contador documentado, no como resultados universales de renderizado.

Conviene saberlo si luego procesas el Markdown con tus propias regex: dos de estas cuatro bibliotecas emiten barras externas y una no.

La licencia de la que nadie habla

install-and-import.json. Cada biblioteca se instaló en su propio entorno vacío. Las licencias se confirmaron en tres lugares: los metadatos del registro, el repositorio de GitHub y el archivo METADATA del paquete instalado, que indica License-Expression: GPL-3.0-or-later.

La biblioteca más ligera de esta comparación de instalación — un paquete, 0,2 MiB — es GPL-3.0-or-later. Que eso afecte o no a un proyecto depende de cómo se combine y distribuya el software. Tómalo como un punto de control para quien lleve el tema legal; este artículo no es asesoramiento jurídico. markitdown aparece como no medido aquí porque su instalación y su licencia no quedaron registradas en este artefacto concreto.

Ese intercambio pasa desapercibido porque la licencia es la única propiedad que no aparece en un benchmark.

Las tres son muchísimo más ligeras que las bibliotecas de extracción de artículos de la misma categoría — esas pesan entre 21 y 70 MiB. Un convertidor es algo bastante más pequeño que un extractor, y merece separarse en tu presupuesto de dependencias.

Dos factores de confusión que tuve que corregir antes de que esta tabla fuera verdadera

Los números de arriba son la tercera versión. Las dos primeras estaban mal por motivos que vale la pena nombrar, porque ambos son fáciles de reproducir.

Cinco archivos frente a cuatro. markitdown ejecutó cuatro de estos cinco archivos; los otros tres ejecutaron los cinco. Sumar cada herramienta sobre su propio conjunto daba 98 filas de tabla para markdownify frente a 36 para markitdown y hacía parecer que existía una brecha de capacidades. Sobre los mismos cuatro, el resultado es 36 contra 36: empate exacto. El quinto archivo es el de tablas intensivas, así que el sesgo iba en la peor dirección posible, inflando a los recién llegados frente al incumbente en casi tres veces.

Dos contadores, una columna. el campo publicado md_table_rows de markitdown venía de su propio código, que yo no había leído. Comparar ese número con el mío podía equivaler a comparar dos contadores distintos y no dos convertidores. Su salida Markdown está guardada en disco, así que la solución fue ejecutar un único contador sobre los cuatro; y cuando lo hice, el recuento de markitdown coincidió exactamente con su cifra publicada por archivo (0, 0, 27, 9). Las definiciones sí coincidían; simplemente no podía haberlo sabido sin comprobarlo.

Ninguno de los dos errores habría sido visible en la salida. Ambos habrían producido una tabla segura pero incorrecta.

Quién debería usar qué

¿Vas a alimentar un modelo o a guardar contenido estructurado de páginas como estas? Empieza con markdownify. Empata con markitdown en el número de filas de tabla emitidas bajo este contador, está en el grupo de menor coste en tokens, tiene licencia MIT y se instala en 1,8 MiB. Valídalo con las formas reales de tus páginas antes de estandarizarlo.

¿Tu presupuesto de dependencias se mide en kilobytes y no vas a distribuir el software? html2text. Un paquete, 0,2 MiB, tablas intactas. Revisa primero el tema GPL y ten en cuenta que el último lanzamiento fue en abril de 2025.

¿Ya trabajas en un stack Node? turndown, con turndown-plugin-gfm instalado junto a él — y elimina <script> y <style> del HTML antes de pasárselo, porque turndown no lo hará. Esas dos omisiones cuestan un cuarto más de tokens y destruyen la estructura de la tabla, y ninguna de las dos se ve si no miras la salida.

¿Ya conviertes otros formatos de documento? markitdown maneja PDF, Office y más, y su salida HTML compite bien con los convertidores especializados. Tener una sola dependencia en lugar de dos también cuenta.

Dónde encaja una API gestionada

Las cuatro opciones trabajan sobre HTML que ya tienes. Ninguna descarga una página, renderiza JavaScript ni maneja una capa anti-bot — y en muchos objetivos reales esa es la mitad más difícil.

Nuestra propia pila para desarrolladores en Thunderbit cubre ese lado. POST /distill toma una URL y devuelve Markdown limpio, listo para LLM, con renderizado y extracción ya resueltos; POST /extract devuelve JSON estructurado alineado con un esquema AI que tú proporcionas, lo que da otro tipo de salida — filas en vez de una tabla Markdown que luego tendrías que parsear. Ambas opciones están disponibles desde un servidor MCP y una CLI (npx @thunderbit/thunderbit-cli). Los precios están en la página de precios de Thunderbit.

La comparación honesta: si ya tienes el HTML y quieres Markdown, markdownify es gratis y lo hace bien, y esta tabla te dice cuáles de sus rivales también. Si estás obteniendo las páginas o necesitas filas estructuradas en lugar de prosa, eso es otra compra distinta.

Para ver el panorama más amplio, nuestro resumen de APIs de web scraping cubre opciones alojadas y el pilar de scrapers open source las autogestionadas. Convertir HTML a Markdown en Python es la guía práctica, y qué intenta estandarizar llms.txt explica hacia dónde se dirige esta categoría.

Prueba Thunderbit para extraer datos web

Veredicto

Para esta carga de trabajo de cuatro archivos, markdownify es la mejor opción por defecto: el mismo número de filas de tabla emitidas que markitdown bajo el contador compartido, un número de tokens dentro del 1,3 % de los otros convertidores eficientes, licencia MIT y una instalación de 1,8 MiB.

La conclusión real está en la brecha entre popularidad y comportamiento medido. turndown es una biblioteca excelente que muchísima gente ha instalado sin el plugin que le permite manejar tablas, y el coste de eso aparece como un 24,6 % más de tokens y una estructura de tabla que deja de existir. Ninguna de esas cifras aparece en ningún sitio hasta que las cuentas.

Si te llevas una sola idea: comprueba qué hace tu convertidor con una tabla antes de confiar su salida a un modelo. Tres de estos cuatro hacen algo razonable. El más popular no, salvo que se lo pidas.

Prueba Thunderbit para extraer datos web Get Started Free

Preguntas frecuentes

¿De verdad turndown no admite tablas? Su núcleo no las admite. Las tablas vienen de turndown-plugin-gfm, un paquete aparte, y un npm install turndown normal no lo incluye. Sin el plugin, cada celda sobrevive como su propio párrafo: los valores están todos, pero ya no existen las relaciones de filas y columnas. En cuatro archivos eso produjo cero filas de tabla Markdown y un 24,6 % más de tokens que markdownify para el mismo contenido.

¿Por qué al principio parecía que html2text no tenía tablas? Porque mi contador exigía barras al inicio y al final, y html2text no las emite. Team Name | Year | Wins es Markdown válido y se renderiza correctamente; solo es un estilo distinto de | Team Name | Year |. El contador corregido busca una secuencia de líneas con barras y una fila separadora, como haría un parser, y html2text pasa de 1 fila a 32. Si procesas Markdown con tus propias regex, esa es la diferencia que te va a afectar.

¿La GPL de html2text es realmente un problema? Depende de cómo combines y distribuyas el software. GPL-3.0-or-later puede imponer obligaciones que MIT no impone, así que conviene involucrar a quien lleve la licencia antes de elegirlo para un producto distribuido. Esto es un punto de cumplimiento, no asesoramiento legal; la identidad de la licencia se confirmó en los metadatos del registro, el repositorio y el METADATA del paquete instalado.

¿Estos conteos de tokens sirven para otras páginas? La brecha del 24,6 % se debe sobre todo a que turndown conserva el contenido de <script> y <style>, así que escala según cuánto de eso tenga una página: mucho en un CMS moderno, casi nada en una página estática. Las tablas empujan en la dirección contraria: en el archivo que era solo tablas, turndown salió un 22 % más barato, porque no genera estructura de barras. Los bytes por token se mantuvieron entre 3,61 y 3,65 en los cuatro casos, así que la densidad de salida es la misma y la diferencia está en la cantidad. Mide tu propio corpus si esa cifra importa para tu presupuesto.

¿Qué no se probó aquí? Variedad real del mundo: cuatro archivos son cuatro archivos. Listas anidadas, listas de definición, notas al pie y fórmulas. HTML mal formado, que es donde históricamente más divergen los convertidores. Volver a convertir el Markdown a HTML. docling, que tiene los mismos archivos en disco pero cuya ejecución publicada no informa estos campos, así que no aparece en lugar de estimarse. Y la configuración: html2text se ejecutó con body_width=0 porque su valor predeterminado de 78 hace un hard-wrap de cada línea, lo que habría cambiado todos los caracteres y todos los conteos de tokens de esta tabla.