Conversión de Markdown a HTML: reglas y CSS de estilos

Contenido

Cuando escribes artículos para un blog técnico o documentación, muchas veces recurres a la sintaxis de Markdown en lugar de escribir etiquetas HTML a mano, porque es mucho más legible. El problema es que el navegador no interpreta la sintaxis de Markdown tal cual.
Para mostrarla en pantalla hace falta un paso de conversión que transforme el texto Markdown en etiquetas HTML. En este artículo repaso con qué reglas Markdown se convierte en HTML y cómo dar estilo al HTML resultante con CSS.
Reglas por las que la sintaxis de Markdown se convierte en etiquetas HTML
El conversor de Markdown busca en el texto original los patrones de símbolos propios de Markdown y los sustituye por la etiqueta HTML correspondiente. Estas son las sintaxis más habituales y las etiquetas en las que se transforman:
| Sintaxis Markdown | HTML resultante |
|---|---|
# ~ ###### (títulos) | <h1> ~ <h6> |
**negrita** | <strong>negrita</strong> |
*cursiva* | <em>cursiva</em> |
[texto](dirección) | <a href="dirección">texto</a> |
| Texto entre acentos graves (backticks) | <code>texto</code> |
Cada conversor tiene sus propios matices. Por ejemplo, si el tramo marcado en negrita (**) queda pegado justo antes de una partícula gramatical o de otra letra, es decir, si después del signo de cierre viene texto directamente, sin espacio ni signo de puntuación, algunos conversores no lo reconocen como énfasis y dejan los asteriscos a la vista.
Cuando el énfasis no se aplica, casi siempre basta con añadir un espacio después del ** de cierre.
Cómo dar estilo al HTML convertido con CSS
Si te limitas a convertir el Markdown, el HTML se queda con los estilos por defecto del navegador: sin márgenes y con un aspecto bastante plano. Para ganar legibilidad conviene aplicar CSS tipográfico al contenedor que envuelve el resultado de la conversión. Estos son algunos ejemplos habituales:
/* Contenedor de nivel superior que envuelve el resultado del renderizado de Markdown */
.markdown-body {
line-height: 1.6;
color: #24292e;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica;
}
/* Añade una línea divisoria sutil bajo los títulos */
.markdown-body h2 {
padding-bottom: 0.3em;
border-bottom: 1px solid #eaecef;
}
/* Mejora la legibilidad de las zonas de código */
.markdown-body code {
padding: 0.2em 0.4em;
background-color: rgba(27, 31, 35, 0.05);
border-radius: 3px;
font-family: SFMono-Regular, Consolas, monospace;
}
En lugar de ejecutar un script de conversión en la terminal cada vez, con el Conversor Bidireccional de Markdown y HTML ves al instante el Markdown que escribes a la izquierda y, a la derecha, la vista previa y el código HTML. También funciona al revés: pegas código HTML y lo devuelves a Markdown.
Si quieres probarlo tú mismo. Escribe tu Markdown abajo y podrás ver el código HTML junto con la vista previa.
Escribe libremente texto o símbolos de Markdown en el panel izquierdo y comprueba en tiempo real la vista previa con estilos y las etiquetas HTML sin procesar que genera.
Puntos con los que uno suele atascarse
| Situación | Causa |
|---|---|
La negrita (**) no se aplica | Después del signo de cierre viene texto directamente, sin espacio ni signo de puntuación |
| El Markdown dentro de un bloque de código se convierte igualmente | La valla de código (```) no está bien cerrada |
| El texto que contiene acentos graves se rompe | El número de acentos graves no cuadra y el tramo de código se delimita mal |
| La imagen no se ve | En  la dirección es una ruta relativa que no coincide con la ubicación real del archivo |
En resumen
Markdown es una sintaxis que el navegador no lee directamente, así que siempre hace falta un paso de conversión a HTML. La sintaxis básica —títulos, énfasis, enlaces, código— sigue reglas parecidas en la mayoría de conversores, pero hay detalles en los que el comportamiento cambia, como que la marca de énfasis no funcione delante de una partícula coreana. El HTML resultante no trae estilos propios, así que hay que añadirle CSS tipográfico para que se vea bien.
Escribe libremente texto o símbolos de Markdown en el panel izquierdo y comprueba en tiempo real la vista previa con estilos y las etiquetas HTML sin procesar que genera.
Preguntas frecuentes
¿Qué conviene usar primero, Markdown o HTML?
A la hora de escribir, Markdown es más cómodo. No tienes que teclear etiquetas y el archivo de texto se lee bien por sí solo. Solo necesitas convertirlo a HTML cuando lo publiques en la web.
¿Por qué el resultado cambia un poco según el conversor?
Markdown tiene estándares como CommonMark, pero cada conversor añade sintaxis extendidas y resuelve las excepciones a su manera. Un mismo texto original puede dar un HTML ligeramente distinto si cambias de conversor.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano