La comparación breve
Elige Markdown cuando lo más importante sea la velocidad de escritura, un origen legible, la portabilidad y los diffs del control de versiones. Elige HTML cuando el documento necesite semántica o componentes que Markdown no pueda expresar, o cuando la página web renderizada sea directamente tuya.
| Aspecto | Markdown | HTML |
|---|---|---|
| Legibilidad del origen | Alta para documentos habituales | Más marcado alrededor del contenido |
| Control de la presentación | Delegado al renderizador | Control detallado con CSS |
| Vocabulario del documento | Reducido y con criterio propio | Amplio conjunto de elementos semánticos |
| Portabilidad | Fuerte dentro de la sintaxis común | Fuerte en la web |
| Interactividad | Normalmente ninguna | Posible con scripts y componentes |
| Superficie de seguridad | Depende del renderizador | El contenido activo exige controles estrictos |
Dónde es más fuerte Markdown
Markdown mantiene a los autores centrados en la jerarquía y las palabras del documento. Un encabezado es un encabezado sin decisiones sobre nombres de clase, tokens de espaciado ni breakpoints responsivos. Eso hace más rápida la escritura técnica habitual y más calmados los diffs de revisión.
La contrapartida es que el renderizador tiene la última palabra. La misma tabla o lista de tareas puede verse distinta en GitHub, un editor y un generador de sitios estáticos, y algunas extensiones pueden no existir en todas partes.
Dónde es más fuerte HTML
HTML puede representar navegación, figuras, paneles de detalles, formularios, definiciones, medios y relaciones de accesibilidad ricas que el Markdown básico no puede. Combinado con CSS, admite maquetados precisos y sistemas de diseño.
Ese poder añade responsabilidad. Los autores o los sistemas de componentes deben producir semántica válida, interacción compatible con teclado, estilo responsivo y un límite de contenido seguro. El HTML sin procesar de un documento no confiable nunca debe inyectarse sin higienización.
La mayoría de los sistemas de documentación usan ambos
Una canalización habitual guarda los artículos en Markdown, los convierte a HTML y luego aplica componentes y CSS compartidos. Los autores obtienen un origen legible, mientras que el sitio web recibe navegación, resaltado de sintaxis, maquetado responsivo y funciones de accesibilidad.
Algunos sistemas permiten HTML sin procesar dentro de Markdown. Usa esa válvula de escape con moderación: reduce la portabilidad y puede ampliar la superficie de seguridad. Prefiere un componente o una extensión documentada cuando la plataforma de publicación los ofrezca.
Markdown: ## API reference [Read the schema](/schema) HTML: <h2>API reference</h2> <a href="/schema">Read the schema</a>
Convertir HTML a Markdown es deliberadamente con pérdidas
Los encabezados, párrafos, enlaces, listas, código y tablas simples semánticos suelen tener equivalentes claros. El maquetado CSS, los nombres de clase, los scripts, los formularios y los widgets personalizados no los tienen. Una buena conversión conserva el documento legible y deja atrás la aplicación web.
Tras la conversión, inspecciona los enlaces relativos, las referencias a imágenes, las vallas de código y cualquier fragmento sin procesar. La vista previa del editor debe higienizar la salida no confiable, pero la publicación aún merece su propia política de contenido.