Markdown vs HTML: cuándo usar cada uno

Resumen. Markdown es un formato fuente amigable para escritores que compila a HTML. HTML es el objetivo de renderizado que todo navegador, cliente de correo y CMS consume en última instancia. Escribe en Markdown para prosa; usa HTML en línea para diseños complejos, formularios y elementos interactivos.

Markdown y HTML se discuten frecuentemente como alternativas. No lo son. Markdown es un formato fuente amigable para escritores que compila a HTML. HTML es el formato universal de renderizado de documentos que los navegadores, clientes de correo y la mayoría de generadores de sitios estáticos consumen en última instancia. La pregunta no es cuál elegir — es en cuál deberías estar escribiendo.

Las diferencias principales

Cuándo gana Markdown

• Archivos README, documentación, entradas de blog. Su razón de ser. Se lee mientras se escribe, sin ruido de etiquetas, las diferencias en control de versiones son limpias.
• Comentarios, issues, mensajes de chat. GitHub, Discord, Slack y toda herramienta de colaboración moderna acepta Markdown. Negrita, enlaces, bloques de código, listas — universal.
• Generadores de sitios estáticos. Hugo, Jekyll, Next.js MDX y todo motor de blog moderno toma Markdown como entrada.
• Donde domina la prosa. Markdown está optimizado para “texto con formato ocasional” — exactamente la proporción que los escritores necesitan.

Cuándo gana HTML

• Cualquier cosa con diseño complejo. Múltiples columnas, tablas con estilo a nivel de celda, posicionamiento personalizado. Markdown no puede expresar lo que CSS espera.
• Páginas web en producción. El navegador solo renderiza HTML. Incluso cuando tu fuente es Markdown, la página desplegada es HTML.
• Correo electrónico. La mayoría de clientes de correo renderizan HTML; muy pocos renderizan Markdown directamente. Los correos de marketing usan HTML + estilos en línea porque los clientes de correo estropean cualquier cosa más sofisticada.
• Elementos interactivos. Formularios, scripts, iframes, atributos de accesibilidad (aria-*, role) — territorio exclusivo de HTML.

El problema de las variantes

“Markdown” no es una especificación única. Existen varias variantes incompatibles:

• CommonMark (2014, en curso) — el esfuerzo de estandarización. Estricto y predecible. La base a la que se adhieren la mayoría de los analizadores modernos.
• GitHub Flavored Markdown (GFM) — CommonMark más tablas, tachado, listas de tareas, autoenlaces. El estándar de facto para documentación de desarrolladores.
• Pandoc Markdown — extendido para uso académico y de libros de gran extensión: notas al pie, citas, listas de definición, matemáticas via LaTeX.
• Markdown original de John Gruber (2004) — con especificación incompleta en algunos puntos. Diferentes analizadores gestionan los casos extremos de forma distinta.

Si la portabilidad importa, escribe en CommonMark y evita las extensiones específicas de cada variante.

HTML dentro de Markdown

La mayoría de los analizadores de Markdown permiten insertar HTML en línea cuando Markdown no es suficientemente expresivo. Esta es la válvula de escape pragmática — mantén el 95% de tu documento en Markdown, usa HTML para la tabla que necesita colspan en celdas, el iframe que inserta un vídeo, el formulario.

Algunos analizadores (el de StackOverflow, por ejemplo) eliminan la mayoría del HTML por seguridad. Comprueba el contexto de renderizado antes de depender de esto.

La regla pragmática

• Escritura: Markdown. Empieza siempre en Markdown.
• Lectura: HTML. El navegador/correo renderiza la salida HTML de tu Markdown.
• Casos extremos: usa HTML en línea donde sea necesario.
• Email marketing, diseños complejos, web en producción: HTML directamente.

Datos numéricos

• Longitud de la especificación Markdown: CommonMark 0.31 tiene ~70 páginas impresas; el WHATWG HTML Living Standard tiene más de 1.400 páginas.
• Proporción de pulsaciones: para un artículo típico de 500 palabras con 6 enlaces y 3 encabezados, el fuente Markdown tiene ~620 caracteres frente a ~1.050 del HTML equivalente — aproximadamente 40% menos pulsaciones.
• Velocidad de análisis: markdown-it analiza ~150 MB/s de CommonMark en un portátil de 2024; los analizadores HTML modernos (lxml, html5ever) están en 200-400 MB/s. Ambos son lo suficientemente rápidos para que el análisis nunca sea el cuello de botella.
• Soporte de tablas en GFM: GitHub Flavored Markdown limita las tablas a 64 columnas; la especificación de CommonMark no tiene sintaxis nativa de tablas en absoluto.
• Señal de adopción: ~99% de los README en GitHub son Markdown (GitHub informa que el recuento supera los 280 millones de archivos).

Matriz de decisión lado a lado

Dónde se esconden los problemas

Tres modos de fallo recurrentes en equipos que adoptan Markdown para pipelines de documentación:

• Párrafos con salto de línea duro vs suave. CommonMark trata un solo salto de línea dentro de un párrafo como un espacio; GFM sigue la misma regla pero algunos analizadores heredados (RedCarpet antiguo, Pandoc vintage) lo tratan como un<br> literal. La solución: nunca insertes saltos de línea dentro de un párrafo a menos que quieras un salto de línea.
• Reescritura de comillas tipográficas. Pandoc, Hugo y algunos plugins de Jekyll reescriben silenciosamente las comillas rectas en comillas tipográficas curvas — bien para prosa, catastrófico dentro de un ejemplo de código sin vallar. Usa siempre bloques de código vallados (triple backtick) para todo lo que contenga comillas.
• Sangría de listas. CommonMark requiere que los elementos de listas anidadas tengan una sangría de 2 o 4 espacios (coincidiendo con el desplazamiento del marcador del elemento de lista padre). Las tabulaciones se renderizan de forma diferente en distintos analizadores; nunca mezcles tabulaciones y espacios dentro de la misma lista.

Fuentes

• CommonMark Specification 0.31.2 — spec.commonmark.org (gramática canónica de Markdown).
• WHATWG HTML Living Standard — html.spec.whatwg.org (referencia autoritativa de HTML).
• GitHub Flavored Markdown Spec — github.github.com/gfm (superconjunto de CommonMark que usa GitHub).