HTML a Markdown: Cuándo convertir y qué perderás
📷 Ilya Pavlov / PexelsHTML a Markdown: Cuándo convertir y qué perderás
Convertir HTML a Markdown no es sin pérdidas. Aprende qué se traduce limpiamente, qué se rompe y cómo hacerlo correctamente con herramientas gratuitas.
Si has pasado tiempo trabajando con contenido en la web, probablemente has experimentado el momento en que tienes un montón de HTML y desearías que fuera Markdown. O al revés. Los dos formatos coexisten en el mundo del desarrollador en una relación inestable — HTML es el lenguaje de la web, Markdown es el lenguaje de las personas que escriben para la web.
Esta guía trata sobre esa conversión: cuándo tiene sentido, qué estás intercambiando, y cómo hacerlo eficientemente.
Qué es Markdown y por qué los desarrolladores lo aman
Markdown fue creado por John Gruber y Aaron Swartz en 2004 con un objetivo simple: crear un formato de texto plano que se lea naturalmente tal cual, pero que también pueda convertirse en HTML limpio.
Tuvo un éxito arrollador. Hoy Markdown impulsa los READMEs de GitHub, wikis de GitLab, páginas de Notion, vaults de Obsidian, sitios de documentación e innumerables plataformas de blog. Si alguna vez has escrito **negrita** o # Encabezado en un editor de texto, has escrito Markdown.
El atractivo es real. Compara escribir en HTML sin formato:
<h2>Primeros pasos</h2>
<p>Instala el paquete con <code>npm install my-package</code> y luego impórtalo:</p>
<ul>
<li>Importar la exportación predeterminada</li>
<li>Llamar a la función <code>init()</code></li>
</ul>
Versus Markdown:
## Primeros pasos
Instala el paquete con `npm install my-package` y luego impórtalo:
- Importar la exportación predeterminada
- Llamar a la función `init()`
La misma información. La versión Markdown es más rápida de escribir, más fácil de leer en forma bruta y menos propensa a errores (sin etiquetas de cierre olvidadas).
Cuándo realmente querrías convertir HTML a Markdown
La conversión suele surgir en un puñado de situaciones específicas.
Migrar de un CMS a un generador de sitios estáticos
Este es el caso grande. Tienes un sitio WordPress, o un sitio Wix, o un CMS personalizado que almacena contenido como HTML en una base de datos. Quieres migrar a Gatsby, Hugo, Jekyll o Astro — todos trabajan nativamente con archivos Markdown.
El contenido todavía existe; solo está en el formato incorrecto. En lugar de reescribir cientos de publicaciones a mano, exportas el HTML y lo conviertes en masa a Markdown.
Escribir READMEs de GitHub y documentación
GitHub renderiza Markdown hermosamente, pero a veces tu material fuente existe como HTML — una página web, un sitio de documentación, un brief de diseño en formato de texto enriquecido. En lugar de copiar y pegar HTML desordenado en tu README, conviértelo primero a Markdown limpio.
Archivar o reutilizar contenido web
Supongamos que has raspado o descargado una página web y quieres archivar su contenido en un formato legible y editable. HTML con todas sus clases, IDs, scripts y píxeles de seguimiento es una pesadilla para leer. Markdown limpio de ese ruido es limpio y portátil.
Limpiar pegados de texto enriquecido
Esto sucede constantemente: copias texto de una página web o Google Doc y lo pegas en tu editor. Terminas con HTML oculto o formato de texto enriquecido que causa todo tipo de problemas.
Qué se pierde en la conversión
El estilo CSS desaparece. Tamaños de fuente, colores, espaciado personalizado, bordes, fondos — nada de eso sobrevive.
El soporte de tablas complejas es parcial. Markdown soporta tablas básicas (via la extensión GitHub Flavored Markdown), pero solo las simples.
Los atributos HTML más allá de href y src se eliminan. Atributos data-*, class, id, style, aria-* — los equivalentes Markdown de enlaces e imágenes no los llevan.
Componentes personalizados e incrustaciones. iFrames, incrustaciones de video, elementos HTML personalizados — Markdown no tiene equivalente.
La conversión inversa es sin pérdidas. Markdown a HTML es una conversión completa. La dirección contraria es con pérdidas. Guarda una copia de seguridad.
Cómo funciona realmente la conversión
Los conversores HTML-a-Markdown funcionan analizando el HTML en un árbol DOM y luego recorriendo cada elemento, traduciéndolo a su equivalente Markdown:
<h1>a<h6>se convierten en#a######<p>se convierte en un párrafo con líneas en blanco alrededor<strong>y<b>se convierten en**negrita**<em>y<i>se convierten en*cursiva*<a href="...">se convierte en[texto](url)<img src="...">se convierte en<ul>y<ol>se convierten en listas Markdown<code>se convierte en código envuelto en backticks- Los bloques
<pre><code>se convierten en bloques de código delimitados
Usar nuestra herramienta gratuita HTML a Markdown
Nuestro conversor HTML a Markdown maneja los escenarios de conversión más comunes sin ninguna instalación o configuración.
Cómo usarla:
- Pega tu HTML en el panel de entrada a la izquierda
- La salida Markdown aparece instantáneamente a la derecha
- Revisa la conversión por cualquier cosa que parezca incorrecta
- Copia el Markdown y úsalo donde lo necesites
Si quieres ver una vista previa de cómo se renderizará tu Markdown, la herramienta Markdown Preview te permite pegar Markdown y ver la salida HTML renderizada en paralelo.
Conversión manual vs herramientas automatizadas
La conversión manual te da control total. Puedes hacer juicios de valor. El resultado es exactamente lo que quieres. Pero no escala.
Las herramientas automatizadas manejan conversiones masivas y son rápidas. Casi siempre necesitarás un pase de limpieza, especialmente para:
- Elementos de navegación que se incluyeron en la conversión
- Texto boilerplate (avisos de cookies, CTAs de newsletter)
- Artefactos de formato extraños de diseños CSS complejos
Herramientas y bibliotecas especializadas
Turndown.js (JavaScript) es probablemente la biblioteca HTML-a-Markdown más ampliamente utilizada en el ecosistema Node.js.
const TurndownService = require('turndown');
const turndownService = new TurndownService();
const markdown = turndownService.turndown('<h1>Hola Mundo</h1>');
Pandoc es la navaja suiza de la conversión de documentos. Convierte entre docenas de formatos: HTML, Markdown, Word, PDF, LaTeX y más.
html2text (Python) es una biblioteca Python ligera para convertir HTML a texto plano en estilo Markdown.
Markdownify es otra opción de Python, específicamente enfocada en HTML-a-Markdown con salida limpia.
Mejores prácticas para conversiones limpias
Limpia tu HTML antes de convertir. Si es posible, elimina navegación, pies de página, barras laterales y otro contenido boilerplate antes de alimentar el HTML al conversor.
Revisa la estructura de encabezados. Si el HTML fuente tenía niveles de encabezado inconsistentes, el Markdown convertido tendrá el mismo problema.
Maneja los enlaces con cuidado. Los enlaces relativos que tenían sentido en el sitio original no lo tendrán en tus nuevos archivos Markdown.
Verifica las rutas de imágenes. Las referencias de imágenes en Markdown necesitan apuntar a URLs accesibles o rutas de archivos locales.
Prueba el renderizado después de la conversión. Pega tu Markdown convertido en una herramienta de vista previa (Markdown Preview) y compáralo con el original.
Un flujo de trabajo de migración práctico
- Exporta tu contenido desde el CMS fuente
- Si obtienes archivos HTML, pásalos por un conversor masivo o script usando Turndown.js o pandoc
- Haz una primera revisión — busca artefactos de conversión obvios
- Actualiza las rutas de imágenes y enlaces rotos
- Verifica la estructura de encabezados y corrige problemas de jerarquía
- Pasa los archivos Markdown finales por una herramienta de vista previa
- Importa a tu nuevo sitio y verifica la salida en vivo
Cuándo no convertir
Si tu página tiene componentes interactivos complejos — pestañas controladas por JavaScript, acordeones, contenido dinámico — convertir el shell HTML a Markdown eliminará exactamente las cosas que hacen que la página funcione.
Si el formato visual preciso es crítico (páginas de aterrizaje, materiales de marketing), la falta de control de estilo de Markdown lo hace inadecuado.
Pensamientos finales
HTML y Markdown sirven a diferentes propósitos y diferentes audiencias. HTML es para navegadores. Markdown es para humanos que escriben cosas que terminan en navegadores.
La conversión entre ellos es un problema resuelto — las herramientas existen, son buenas, y son gratuitas. La habilidad real es saber cuándo la conversión añade valor y cuándo no, y saber cómo limpiar la salida para que sea realmente utilizable.
Para conversiones rápidas y únicas, nuestra herramienta HTML a Markdown es el camino más rápido. Para migraciones más grandes, combínala con un enfoque programático y un sólido proceso de revisión.
De cualquier manera, una vez que tu contenido esté en Markdown, probablemente te preguntarás por qué alguna vez lo mantuviste en HTML.