Conversor de HTML a Markdown

Qué hace realmente la conversión de HTML a Markdown

Un conversor de HTML a Markdown analiza un fragmento HTML, recorre el árbol DOM resultante y emite sintaxis Markdown para cada elemento que reconoce. <h1> se vuelve #; <strong> se vuelve **negrita**; <a href="..."> se vuelve [texto](url); <ul><li> se vuelve una lista con viñetas. La herramienta se ejecuta enteramente en tu navegador vía JavaScript: pega HTML a la izquierda, pulsa Convertir a Markdown y la salida formateada aparece a la derecha. Sin subida, sin viaje al servidor, sin telemetría: verifícalo en la pestaña Red de DevTools mientras pulsas Convertir, o pon la página fuera de línea (modo avión) tras cargarla y el conversor seguirá funcionando. Esta implementación usa el DOMParser integrado del navegador para leer el HTML, y luego un pequeño recorrido recursivo emite el Markdown para cada nodo. Es un conversor de unas 150 líneas escrito a mano en lugar de un envoltorio sobre Turndown, lo que significa que cubre el caso común limpiamente pero no iguala la configurabilidad completa de Turndown.

Cuándo necesitas realmente esta conversión

El sentido inverso (Markdown a HTML) es el famoso: lo hace todo generador de sitios estáticos y toda herramienta de escritura. El sentido directo (HTML a Markdown) es menos obvio pero cada vez más común porque el ecosistema de herramientas de escritura se ha polarizado: HTML es el formato ambiente de la web (todo CMS, plataforma de newsletter, plantilla de CRM, sitio estático antiguo emite o almacena HTML); Markdown es el formato nativo de todo flujo moderno de documentación, toma de notas y contenido bajo control de versiones aparecido desde alrededor de 2014. Cuatro flujos del mundo real generan esta necesidad de conversión.

• Captura de artículos para apps de notas. Guardar un artículo web en Obsidian, Notion, Logseq o Roam: todos almacenan notas como archivos Markdown. El Web Clipper oficial de Obsidian (lanzado en 2024) y la popular extensión de navegador MarkDownload siguen este patrón: extraer el DOM del artículo con la biblioteca Readability de Mozilla, convertir a Markdown, guardar a disco. Cuando no puedes alcanzar el HTML subyacente a través de una extensión (contenido tras un muro de pago, lectores incrustados, contenido que llega por correo), copia el texto renderizado, pega el HTML resultante en un conversor y guarda el Markdown.
• Migración de CMS a un SSG Markdown-first. Mover documentación de WordPress, Confluence, Drupal, Mediawiki o Movable Type a MkDocs (Tom Christie, Python), Docusaurus (Meta, React), Hugo (Steve Francia, Go), Jekyll (Tom Preston-Werner, Ruby, sigue siendo el motor tras GitHub Pages), Eleventy (Zach Leatherman, Node), VitePress (Evan You, Vue), o Sphinx-with-MyST. Todos son nativamente Markdown; el contenido CMS existente tiene que exportarse como HTML y convertirse en bloque.
• Salida de editor WYSIWYG a Markdown portable. Una redactora usa Google Docs, Word, Apple Notes, Evernote o el editor rich-text de un CMS y la carga útil del portapapeles es HTML. Quiere Markdown limpio para hacer commit a Git, pegar en un editor Markdown, enviar a un desarrollador o incluir en un sitio de docs. La opción «Guardar como página Web» de Microsoft Word produce un HTML notoriamente denso -lleno de espacios de nombres XML, CSS prefijado mso-, etiquetas específicas de Office- y un conversor que ignora todo lo que no entiende y emite Markdown limpio es exactamente la herramienta de limpieza adecuada.
• Contenido de correo para archivado. Las plataformas de newsletter (Substack, Kit/ConvertKit, Beehiiv, Mailchimp) envían todas HTML formateado. Un lector que guarda material de referencia en Markdown puede ver el código fuente del cuerpo del correo, pegar el HTML en un conversor y archivar el resultado en sus notas.

La implementación de referencia: Turndown y su familia

Turndown (Dom Christie) es la biblioteca JavaScript de HTML a Markdown dominante: empezó como to-markdown en 2012, se renombró a Turndown en 2017 para distinguirlo de los forks, y se publica como turndown en npm bajo licencia MIT. Su diseño es basado en reglas: cada regla tiene un filter (qué nodos del DOM dispara) y un replacement (una función que produce el Markdown). El constructor acepta opciones para estilo de encabezado (atx # vs setext ===), marcador de viñeta (-, + o *), estilo de bloque de código (indentado vs cercado), delimitador de énfasis (* vs _), delimitador de negrita (** vs __), estilo de enlace (en línea vs referenciado), etc. Tablas, tachado, ítems de lista de tareas y autoenlaces viven en el paquete separado turndown-plugin-gfm. markdownify (Matthew Tretter) es el equivalente en Python: muy usado en pipelines de scraping, conversión de notebooks Jupyter, cargadores de documentos de LangChain y preparación de datasets para LLM. html2text (originalmente de Aaron Swartz, que también colaboró con John Gruber en el diseño original de Markdown en 2004) es la opción Python más antigua, todavía en uso en pipelines de correo heredados pero en gran medida superada. html-to-markdown (Johannes Kaufmann) es un port Go de Turndown popular para binarios de scraping autocontenidos. Pandoc (John MacFarlane, que preside el proyecto CommonMark) es el conversor universal de documentos: maneja tablas con celdas fusionadas vía grid tables, matemáticas, citas, notas al pie, listas de definiciones y convierte entre docenas de formatos. Pandoc es la herramienta de HTML a Markdown más completa disponible, pero es un binario Haskell de más de 60 MB que hay que instalar; no se ejecuta en un navegador.

El compromiso fundamental: HTML es más rico que Markdown

Toda conversión de HTML a Markdown es necesariamente con pérdida porque el formato origen expresa cosas que el destino no puede. Los estilos en línea (<span style="color:red">) no tienen gramática Markdown: el vocabulario de énfasis de Markdown se limita estrictamente a negrita/cursiva/tachado/código, sin sintaxis para color, fuente o tamaño arbitrarios. Las clases CSS (<div class="alert">) tienen significado para una hoja de estilos pero no para Markdown. Los atributos data personalizados (data-track-event="...") son parte del contrato JavaScript de la página, no del documento. Las tablas con celdas fusionadas (colspan, rowspan) no pueden expresarse en pipe tables GFM. Los medios incrustados (<video>, <audio>, <iframe>) y los controles de formulario no tienen equivalente en Markdown. Los plegables <details><summary>, los <figure><figcaption>, las anotaciones <ruby> para pronunciación CJK, microdatos y microformatos: nada de eso sobrevive a la conversión. Para cada construcción no soportada, el autor del conversor elige una de tres estrategias: traducir a una aproximación Markdown que pierde información, dejar pasar como HTML puro incrustado dentro del Markdown (Markdown lo permite por especificación; las secciones 4.6 y 6.6 de CommonMark lo cubren), o descartar del todo. Esta implementación elige «traducir donde haya un mapeo claro, y si no, envoltura transparente (renderizar los hijos, descartar la etiqueta)»: un comportamiento por defecto predecible y fácil de razonar que cubre el caso común a costa de la configurabilidad avanzada.

Las correspondencias canónicas

• Encabezados: <h1>–<h6> mapean a # hasta ###### (estilo atx). La forma setext más antigua (subrayados === y ---) también es válida para h1 y h2 pero rara en 2026.
• Párrafos: <p> se vuelve texto plano con líneas en blanco a su alrededor. Una ruptura de párrafo en Markdown es una o más líneas en blanco.
• Énfasis: <strong> y <b> se vuelven **negrita**. <em> y <i> se vuelven *cursiva*. <del> y <s> se vuelven ~~tachado~~ (extensión GFM; no en CommonMark propiamente dicho).
• Enlaces: <a href="url">texto</a> se vuelve [texto](url). La forma de enlace por referencia ([texto][1] con [1]: url al final) también es Markdown válido.
• Imágenes: <img src="url" alt="texto"> se vuelve ![texto](url). El signo de exclamación distingue las imágenes de los enlaces.
• Código: <code> se vuelve spans en línea con comillas inversas. <pre><code> se vuelve un bloque cercado con triple comilla inversa. Esta implementación maneja correctamente el requisito CommonMark de que los spans de código en línea usen una valla más larga cuando el contenido contiene comillas inversas (según la regla de la especificación §6.1 de CommonMark).
• Listas: <ul> se vuelve líneas con viñetas -; <ol> se vuelve líneas numeradas 1., 2., ... CommonMark acepta cualquier número inicial; los renderizadores normalizan.
• Citas en bloque: <blockquote> antepone a cada línea de los hijos un >.
• Líneas horizontales: <hr> se vuelve --- en su propia línea. *** y ___ también son válidos.
• Saltos de línea: <br> se vuelve un salto de línea. CommonMark también acepta dos espacios al final o una barra invertida al final de la línea.
• Tablas: <table> se vuelve una tabla pipe GFM: fila de encabezado, fila delimitadora de ---, filas del cuerpo. Extensión GFM; no en el núcleo de CommonMark.

Alcance honesto: lo que esta herramienta hace y no hace

Tres limitaciones honestas que conviene conocer. (1) Los estilos en línea y las clases CSS se descartan. Un <span style="color:red"> queda como texto sin estilo; un <p class="lede"> pierde su clase. No hay gramática Markdown para estilo en línea arbitrario. (2) Las tablas con celdas fusionadas se aplanan. Las pipe tables GFM no tienen sintaxis para colspan o rowspan; la información de fusión se descarta silenciosamente. Para tablas complejas, mantén la fuente como HTML dentro del Markdown (CommonMark permite HTML incrustado) o usa Pandoc con salida grid table. (3) Los bloques de código se emiten sin pista de lenguaje. Si tu HTML contiene <pre><code class="language-js">, el atributo de lenguaje se descarta actualmente: la salida es un bloque cercado sin lenguaje. Puedes añadir manualmente el identificador de lenguaje tras las comillas inversas de apertura si tu renderizador destino soporta resaltado de sintaxis. La advertencia mayor: si pegas el HTML completo de una página web (de «Ver código fuente»), los contenidos <script> y <style> se emitirán como texto plano -casi seguro que no es lo que quieres. La solución: pega solo el contenido del artículo, copia desde la vista renderizada (que retira scripts y estilos automáticamente) o sanea el HTML con DOMPurify o similar antes de la conversión.

La forma de Markdown en 2026

Markdown cumplió veintidós años en 2026. John Gruber publicó el script Perl original en 2004 con Aaron Swartz como colaborador de diseño. Las tablas se omitieron deliberadamente del original de Gruber; la sintaxis de pipe-tables que la mayoría de los lectores conocen hoy proviene de dialectos posteriores, sobre todo GitHub Flavored Markdown. CommonMark, el riguroso esfuerzo de especificación organizado por Jeff Atwood y John MacFarlane en 2014, está ahora en la versión 0.31.2 (28 de enero de 2024) y es el dialecto al que apuntan la mayoría de los parsers modernos. GitHub Flavored Markdown (GFM, formalizado en la versión 0.29-gfm el 6 de abril de 2019) es el superset GFM que añade tablas, listas de tareas, tachado, autoenlaces y reglas de HTML-bruto-prohibido. GFM es el dialecto que la mayoría de los usuarios ven realmente en la web por la escala de GitHub. Markdown es ahora el formato nativo de prácticamente todo ecosistema de documentación para desarrolladores; HTML sigue siendo el formato de salida universal de la web; la conversión entre ambos es exactamente tan común como la inversa, y existe para el momento en que la necesitas con prisa, en un navegador, sin instalación y sin que ningún dato salga de tu dispositivo.

Privacidad: por qué importa el solo-navegador aquí

El HTML pegado en un conversor a menudo contiene rastros del origen -marcado interno del CMS, contenido en borrador todavía no publicado, datos de cliente dentro de plantillas de correo, URL de enlaces que revelan estructura interna del sitio, referencias de imagen que apuntan a servidores de assets privados. Los conversores del lado servidor suben todo eso a un servicio de terceros. Esta herramienta se ejecuta enteramente en tu navegador vía JavaScript: el HTML que pegas nunca cruza la red -verifícalo en la pestaña Red de DevTools mientras pulsas Convertir, o pon la página fuera de línea (modo avión) tras cargarla y el conversor seguirá funcionando. Seguro para borradores no publicados, plantillas de correo de cliente, extractos de documentación interna o cualquier HTML que no quieras ver copiado en el disco duro de un desconocido.

Preguntas frecuentes

¿Funciona con archivos grandes?

Sí: como la conversión se ejecuta en tu navegador, el techo práctico es la memoria disponible de tu dispositivo. Decenas de miles de líneas se convierten en mucho menos de un segundo en un portátil moderno. Entradas muy grandes (millones de nodos) pueden congelar brevemente la pestaña mientras el recorrido del DOM hace recursión. Para conversión por lotes de toda una exportación de CMS, un script con Turndown en Node o markdownify en Python es la herramienta mejor.

¿Qué les ocurre a los estilos en línea y las clases CSS?

Se descartan por completo. La gramática de énfasis de Markdown cubre negrita, cursiva, tachado y código; no hay sintaxis para color, fuente, tamaño arbitrarios o estilos guiados por clase. Si el estilo visual importa en tu salida, mantén el original como HTML o usa un formato de destino más rico como AsciiDoc, reStructuredText o MDX (Markdown más componentes JSX, usado por Docusaurus). Para los casos de archivado de artículos y migración de CMS para los que esta herramienta está construida, descartar estilos es el comportamiento correcto: el sentido entero de Markdown es retirar el ruido visual y conservar solo la estructura.

¿Funciona esta herramienta sin conexión?

Sí: una vez cargada la página, la conversión se ejecuta enteramente en JavaScript dentro de tu navegador. Sin llamadas de red durante la conversión. Verifícalo en la pestaña Red de DevTools mientras pulsas Convertir, o pon el dispositivo fuera de línea (modo avión) tras cargar la página y la herramienta seguirá funcionando.

¿Esto es Turndown?

No. Turndown (la biblioteca de Dom Christie) es la implementación de referencia en JavaScript y la herramienta obvia a la que recurrir en un proyecto Node, pero es una dependencia considerable con configurabilidad completa para estilo de encabezado, marcadores de viñeta, estilo de enlace, estilo de bloque de código, etc. Esta herramienta en el navegador es un recorrido DOM más pequeño escrito a mano -unas 150 líneas- que apunta al caso común (encabezados, párrafos, énfasis, enlaces, imágenes, listas, citas en bloque, código cercado, tablas básicas) sin la superficie de configuración. Para los flujos para los que está construido este sitio (conversiones puntuales en un navegador, sin instalación), la implementación más pequeña es la forma adecuada; para pipelines de scraping en producción que necesiten reglas configurables, Turndown sigue siendo la elección correcta.

¿Cómo se manejan las tablas?

Como pipe tables GFM: una fila de encabezado, una fila delimitadora de guiones, y una fila de cuerpo por <tr>. Las pipe tables son planas: no pueden representar colspan, rowspan, contenido de celda multilínea, listas dentro de celdas o alineación por celda. Si tu tabla HTML usa cualquiera de esas funciones, este conversor emite una pipe table degradada que pierde la estructura adicional. Para tablas complejas, dos opciones prácticas: (a) mantener la tabla como HTML puro dentro del Markdown -CommonMark permite HTML incrustado- y confiar en que tu renderizador destino lo deje pasar; (b) usar Pandoc con salida grid table, que sí puede expresar celdas fusionadas.

¿Puedo pegar el HTML completo de una página web?

Puedes, pero probablemente no deberías. La fuente completa de una página web moderna contiene etiquetas <script> con código JavaScript, bloques <style> con CSS, píxeles de seguimiento, marcado publicitario y comentarios de plantilla de CMS. Este conversor no elimina explícitamente el contenido de script y estilo, así que todo eso acaba como texto plano en tu salida Markdown. El enfoque limpio: selecciona solo el elemento article en DevTools (clic derecho sobre el artículo, «Inspeccionar», luego clic derecho en el nodo correspondiente del panel Elementos y «Copiar outerHTML»), o usa un paso de extracción de contenido (la biblioteca Readability de Mozilla, o su forma empaquetada en el Modo Lectura de Firefox) antes de pegar. Para flujos basados en extensiones de navegador que manejan el paso de extracción automáticamente, mira Obsidian Web Clipper o MarkDownload.

Herramientas relacionadas