Por qué convertir Markdown a HTML
Markdown es un lenguaje de marcado ligero amistoso para escritores, pero los navegadores solo entienden HTML. El contenido escrito en Markdown debe convertirse a HTML para mostrarse en una página web.
Escenarios comunes:
- Publicación de artículos de blog
- Renderización de sitios de documentación
- Visualización de README
- Salida HTML de editores de texto enriquecido
Correspondencia de sintaxis Markdown y HTML
Encabezados
Markdown:
# Encabezado de nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
HTML:
<h1>Encabezado de nivel 1</h1>
<h2>Encabezado de nivel 2</h2>
<h3>Encabezado de nivel 3</h3>
Párrafo
Markdown: bloques de texto separados por líneas en blanco.
HTML: <p>Párrafo</p>
Énfasis
Markdown:
**Negrita**
*Cursiva*
~~Tachado~~
HTML:
<strong>Negrita</strong>
<em>Cursiva</em>
<del>Tachado</del>
Enlaces
Markdown:
[Texto del enlace](https://example.com)
HTML:
<a href="https://example.com">Texto del enlace</a>
Imágenes
Markdown:
HTML:
<img src="image.png" alt="Texto alternativo">
Listas
Markdown lista no ordenada:
- Elemento 1
- Elemento 2
HTML:
<ul>
<li>Elemento 1</li>
<li>Elemento 2</li>
</ul>
Markdown lista ordenada:
1. Primer elemento
2. Segundo elemento
HTML:
<ol>
<li>Primer elemento</li>
<li>Segundo elemento</li>
</ol>
Código
Markdown código en línea:
Esto es `code` código en línea
HTML: Esto es <code>code</code> código en línea
Markdown bloque de código:
Bloque de código
HTML:
<pre><code>Bloque de código</code></pre>
Con resaltado de lenguaje:
const x = 1;
Tras la conversión incluye marcado de resaltado de sintaxis (requiere librería de resaltado).
Cita
Markdown:
> Esto es una cita
HTML:
<blockquote>Esto es una cita</blockquote>
Línea divisoria
Markdown:
---
HTML:
<hr>
Tabla
Markdown:
| Nombre | Edad |
| ------ | ---- |
| Tom | 25 |
HTML:
<table>
<thead>
<tr><th>Nombre</th><th>Edad</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
Sintaxis extendida
El Markdown estándar (CommonMark) no incluye estas funciones, pero la mayoría de los parsers las soportan:
Lista de tareas
- [x] Completado
- [ ] No completado
HTML:
<ul>
<li><input type="checkbox" checked disabled> Completado</li>
<li><input type="checkbox" disabled> No completado</li>
</ul>
Notas al pie
Texto[^1]
[^1]: Contenido de la nota
Tachado
~~Eliminar~~
Enlaces automáticos
Las URL se convierten automáticamente en enlaces (sin escribir a mano).
Listas de definición, índice, fórmulas, etc.
Algunos parsers las soportan, con compatibilidad variable.
Consideraciones de conversión
Pérdida de estilos
La conversión de Markdown a HTML solo genera etiquetas, sin estilos. El efecto visual depende del CSS:
- Tamaño y espaciado de encabezados
- Sangría y viñetas de listas
- Fondo y fuente de bloques de código
- Bordes de tablas
Hay que configurar el CSS tras la conversión para que se vea bien.
Seguridad XSS
Markdown permite incrustar HTML. Al convertir Markdown introducido por el usuario a HTML, las etiquetas incrustadas como <script> se conservan, provocando XSS.
Prácticas seguras:
- Usar Markdown puro (desactivar HTML incrustado)
- Tras convertir a HTML, filtrar etiquetas peligrosas con una librería sanitize
- Permitir Markdown solo de fuentes fiables
Caracteres de escape
Los caracteres especiales de Markdown (, #, _, ) deben escaparse. Si escribes \* en Markdown se muestra un asterisco; tras convertir a HTML es ` y no una etiqueta.
Ruta de imágenes
Las imágenes con ruta relativa en Markdown mantienen la ruta tras la conversión a HTML. Al cambiar de directorio para mostrar, ajusta la ruta.
Enlaces de anclaje
Los encabezados de Markdown generan automáticamente anclas (id). Los distintos parsers tienen reglas distintas; ten cuidado al enlazar anclas.
Herramientas de conversión
Conversión en línea
Pega Markdown y la herramienta genera HTML. Ideal para conversiones puntuales.
Usa la herramienta Markdown a HTML:
- Pega el contenido Markdown
- La herramienta analiza y convierte
- Genera el código HTML
- Copia y usa
La conversión se realiza en el navegador; el contenido no se sube.
Integración en editores
VS Code, Typora y otros editores tienen previsualización de Markdown a HTML integrada.
Conversión por programa
JavaScript usa las librerías marked, markdown-it. Python usa markdown, mistune.
Consejos de conversión
Unificar el estilo de Markdown
Los distintos dialectos de Markdown (CommonMark, GFM, MDX) pueden dar resultados distintos. El equipo debe unificarse en un dialecto.
Validación con vista previa
Tras la conversión, previsualiza en el navegador y comprueba:
- ¿La jerarquía de encabezados es correcta?
- ¿El anidamiento de listas es normal?
- ¿Los bloques de código tienen resaltado?
- ¿Las tablas están alineadas?
- ¿Las imágenes se muestran?
- ¿Los enlaces son clicables?
CSS complementario
Prepara un CSS de renderización de Markdown y aplícalo al HTML convertido para una visualización atractiva.
Conservar el Markdown original
El HTML es el resultado renderizado; el Markdown es el archivo fuente. Conservar el Markdown facilita ediciones posteriores; el HTML se regenera cada vez.
Preguntas frecuentes
Los estilos no se ven bien tras la conversión
El HTML no tiene CSS. Añade una hoja de estilos de renderización de Markdown.
El bloque de código no se resalta
Necesitas una librería de resaltado de sintaxis (como highlight.js, Prism). Comprueba si la herramienta de conversión integra resaltado.
Desalineación de tablas
La sintaxis de tablas de Markdown no es estricta (el número de columnas no coincide). Revisa el formato de la tabla antes de convertir.
Visualización anómala de caracteres especiales
Los caracteres < > & de Markdown tienen un significado especial en HTML. Deben escaparse como < > &.
Resumen
La conversión de Markdown a HTML tiene como núcleo la correspondencia de sintaxis. Presta atención al CSS complementario, la seguridad XSS y el escape de caracteres especiales. La herramienta Markdown a HTML de DocsAll se ejecuta en el navegador y el contenido no se transmite al exterior.