Cómo convertir HTML a Markdown limpio

Qué convierte bien HTML a Markdown

Los elementos semánticos con un equivalente claro suelen sobrevivir bien: h1–h6 se convierten en títulos, p en párrafos, strong y em en énfasis, ul y ol en listas, a en enlaces, blockquote en citas y pre/code en bloques de código.

Las tablas sencillas también pueden transformarse si tienen filas y celdas regulares. Cuanto más dependa la página de CSS, JavaScript o componentes propios del CMS, más decisiones tendrás que tomar después.

Extrae el artículo, no toda la página

Pegar el código de un documento HTML completo puede producir un Markdown lleno de etiquetas de navegación, enlaces repetidos y mensajes legales. Si tienes acceso al CMS, copia el HTML del campo de contenido. En el navegador, utiliza las herramientas de desarrollo para localizar el elemento main o article y copia ese fragmento.

No necesitas eliminar cada clase CSS antes de convertir: las clases suelen descartarse porque Markdown no describe diseño. Sí conviene excluir bloques que no pertenecen al artículo, ya que el conversor no puede saber si «Suscríbete ahora» forma parte de la explicación o de la plantilla.

• Navegación y migas de pan.
• Avisos de cookies y banners promocionales.
• Artículos relacionados y cajas de suscripción.
• Botones de compartir y comentarios.
• Pie, información legal repetida y enlaces de cuenta.

Cómo convertir HTML a Markdown paso a paso

Trabaja con una copia y compara el resultado con el contenido visible, no con todos los detalles del código fuente.

1. Pega o abre el HTMLAñade un fragmento, un archivo .html o el código del cuerpo de un artículo.
2. Revisa el MarkdownComprueba títulos, enlaces, listas anidadas, tablas, imágenes, citas y bloques de código.
3. Elimina restos de la páginaBorra navegación, llamadas promocionales, enlaces de seguimiento y contenido repetido.
4. Copia o descargaGuarda el .md y pruébalo en el editor, repositorio o sistema de documentación de destino.

Corrige la jerarquía de títulos

Muchas plantillas eligen niveles de título por estilo visual, no por estructura. Un módulo puede usar h4 aunque no exista un h3 anterior, y el nombre del sitio puede aparecer como h1 en todas las páginas. Después de convertir, deja un solo H1 para el título del documento y reorganiza las secciones.

No cambies un nivel solo porque el tamaño de la vista previa no te gusta. El diseño se ajusta con estilos en el destino; Markdown debe expresar la relación entre secciones.

# Nombre del sitio
#### Guía de instalación
## Paso uno
#### Opciones

# Guía de instalación
## Paso uno
### Opciones

Revisa enlaces e imágenes después de mover el contenido

Una URL relativa como /ayuda funciona dentro del dominio original, pero no necesariamente en un repositorio o en otra web. Convierte los enlaces importantes a URLs absolutas o actualízalos a la nueva estructura. Elimina parámetros de seguimiento cuando no sean necesarios.

Las imágenes presentan el mismo problema. Una ruta como ../uploads/foto.jpg depende de la ubicación anterior. Decide si vas a descargar los archivos, subirlos a un nuevo servidor o mantener URL absolutas. Conserva y mejora el texto alternativo; no uses el nombre automático del archivo como descripción.

• Comprueba enlaces internos y externos por separado.
• Retira parámetros utm u otros identificadores de campaña cuando no aporten.
• Busca imágenes con rutas relativas o dominios que se cerrarán tras la migración.
• Escribe texto alternativo que explique la función de la imagen en ese contexto.

Tablas, componentes y contenido que no tiene equivalente

Markdown admite tablas simples en muchos motores de renderizado, pero no celdas combinadas, varias cabeceras o diseños complejos. Simplifica la tabla, conviértela en lista o conserva HTML limitado si el destino lo permite.

Formularios, carruseles, pestañas, acordeones, vídeos incrustados y gráficos interactivos no se convierten en una línea de Markdown universal. Sustitúyelos por un enlace, una imagen estática, una descripción o un componente del nuevo sistema.

Limpia la fuente sin borrar información útil

Después de la conversión, un formateador puede normalizar listas, espacios y separadores. No automatices la eliminación de todo lo que parezca repetido: una advertencia puede aparecer en varios artículos porque sigue siendo importante en cada contexto.

Haz una búsqueda de frases propias de la plantilla, dominios antiguos y URLs de seguimiento. Luego lee el artículo como una persona que llega desde cero. La migración está terminada cuando el contenido se entiende y los enlaces funcionan, no cuando el archivo deja de contener etiquetas HTML.

Control de calidad antes de publicar

Renderiza el Markdown con un motor parecido al del destino y comprueba tanto la fuente como la vista.

• Solo hay un H1 y los niveles de sección siguen un orden lógico.
• Las listas anidadas mantienen su profundidad.
• Las tablas tienen el mismo número de celdas por fila y caben en móvil.
• Los enlaces relativos se han actualizado y no conservan seguimiento innecesario.
• Las imágenes cargan desde su ubicación nueva y tienen texto alternativo útil.
• Los bloques de código conservan espacios, caracteres y lenguaje.
• No quedan navegación, banners, botones de compartir ni texto del pie anterior.
• El contenido no depende de un componente interactivo que desapareció.

Herramientas relacionadas