Markdown y HTML son dos formas de describir lo mismo: texto estructurado. HTML fue diseñado para navegadores; Markdown fue diseñado para personas. Cuando necesitas mover contenido de la web a un entorno de escritura, un sistema de documentación o un generador de sitios estáticos, convertir HTML a Markdown suele ser el camino más rápido. Entender cómo funciona la conversión — y dónde falla — ahorra horas de limpieza manual.
Qué Hace Realmente la Conversión de HTML a Markdown
Un conversor de HTML a Markdown lee un documento HTML y asigna cada elemento HTML a su equivalente en Markdown. El mapeo es mayoritariamente directo: <h1> se convierte en # encabezado, <strong> en **negrita**, <a href="url">texto</a> en [texto](url), <ul><li> en - elemento de lista y <pre><code> en un bloque de código delimitado. El desafío es que HTML es mucho más expresivo que Markdown: existen decenas de elementos HTML que no tienen un equivalente directo en Markdown.
Elementos como <div>, <span>, <table>, <form>, <iframe> y las clases CSS no se mapean limpiamente a Markdown. Los buenos conversores manejan las tablas generando una tabla GFM (GitHub Flavored Markdown), y los elementos no soportados los eliminan o los conservan como HTML en bruto dentro del archivo Markdown. Para contenido que será procesado por un renderizador de Markdown que admita HTML en línea, conservar elementos complejos como HTML en bruto es un enfoque válido.
La biblioteca JavaScript más usada para esto es Turndown, que impulsa muchas herramientas de conversión HTML-a-Markdown en el navegador. Turndown es configurable: puedes elegir entre estilos de encabezado ATX (#) y Setext (subrayado), bloques de código delimitados (```) o indentados, y - o * para las listas. Para mantener consistencia en el control de versiones y mejorar la legibilidad de los diff, se recomiendan los encabezados ATX y los bloques de código delimitados.
Razones Comunes para Convertir HTML a Markdown
- Migración de contenido: mover artículos de un CMS como WordPress a un generador de sitios estáticos (Hugo, Astro, Jekyll) que usa archivos Markdown
- Limpieza de documentación: extraer contenido de documentación HTML heredada para reconstruirla en una herramienta basada en Markdown (GitBook, Docusaurus, VitePress)
- Datos de entrenamiento para IA y LLMs: Markdown es más limpio que HTML para el ajuste fino de modelos de lenguaje porque elimina etiquetas y atributos que añaden ruido sin valor semántico
- Bases de conocimiento personal: recortar artículos web a Markdown para importarlos en Obsidian, Logseq o Notion
- Plantillas de correo electrónico: convertir contenido HTML de emails a Markdown para editarlo antes de volver a renderizarlo como HTML
- Revisión de código: revisar HTML generado por un motor de plantillas comparando la versión Markdown renderizada
Qué Se Pierde en la Conversión
No todo el HTML sobrevive la conversión a Markdown. El estilo (colores, fuentes, clases CSS personalizadas) se pierde completamente — Markdown no tiene concepto de estilo visual. Las imágenes se convierten a la sintaxis  pero todos los atributos de tamaño, alineación y clase se eliminan. Las estructuras anidadas complejas como listas multinivel, listas de definición y tablas con celdas combinadas se simplifican o se convierten a su aproximación más cercana en Markdown.
Los metadatos — el contenido del <head> HTML como las etiquetas <meta>, las URLs canónicas y los datos estructurados — no forman parte del contenido visible y no se convierten. Si migras entradas de blog, deberás extraer estos metadatos por separado y añadirlos como front matter (YAML o TOML) en el archivo Markdown. La mayoría de los generadores de sitios estáticos esperan front matter para el título, la fecha, la descripción y las etiquetas.
Los scripts y los elementos interactivos no tienen equivalente en Markdown y se eliminan completamente. Si conviertes una página con formularios incrustados, carruseles o contenido dinámico, el Markdown convertido solo contendrá el texto estático y el contenido de imagen. Esto es generalmente deseable para flujos de trabajo de documentación y contenido, pero significa que la conversión es con pérdida para páginas interactivas.
La conversión de HTML a Markdown es una herramienta pragmática para la portabilidad del contenido. Funciona mejor con HTML bien estructurado: artículos, documentación, entradas de blog e informes. El resultado no siempre es perfecto, pero te lleva al 90% de un Markdown limpio en segundos, dejando solo una limpieza manual específica para los casos extremos. Para desarrolladores que gestionan migraciones de contenido, construyen sitios de documentación o preparan datos para el entrenamiento de modelos de lenguaje, un conversor de HTML a Markdown es una parte esencial del conjunto de herramientas.