Convertir Markdown a HTML

Un fragmento o una página, y cuál te conviene

Hay dos resultados útiles y no son intercambiables. Un fragmento es solo el marcado convertido (encabezados, párrafos, listas, enlaces) sin la envoltura de documento, que es lo que necesitas cuando el resultado va dentro de una plantilla, un campo de un CMS u otra página. Una página completa agrega el doctype, un head, la declaración del conjunto de caracteres y una hoja de estilos, así que se abre por sí sola y se ve presentable. Pegar una página completa en un CMS te deja un documento dentro de otro documento; abrir un fragmento en un navegador te da texto sin estilo.

La conversión cubre el conjunto ampliado de Markdown en el que hay consenso: encabezados, énfasis, listas, enlaces, imágenes, citas en bloque, tablas, bloques de código con resaltado de sintaxis, listas de tareas, tachado y notas al pie. Los encabezados reciben identificadores derivados de su texto, para que se pueda enlazar directamente a ellos: los enlaces de anclaje que hacen usable una documentación larga.

El HTML sin procesar dentro del Markdown se conserva tal cual, algo que forma parte de la especificación y conviene tener muy presente: significa que un archivo Markdown de origen no confiable puede contener una etiqueta script, y al convertirlo se obtiene una página que lleva ese script. Nunca renderices Markdown de desconocidos sin sanear el HTML después: la conversión no es una barrera de seguridad y nunca pretendió serlo.

Hay dos cosas que se muestran como bloques de código en lugar de renderizarse, a propósito. Las fórmulas matemáticas en notación LaTeX necesitan una biblioteca de composición tipográfica, y los diagramas de Mermaid necesitan un renderizador de diagramas: cada uno es una dependencia considerable, y una ecuación mal renderizada es peor que una visible como código. Una página completa usa fuentes normales del sistema en lugar de descargar alguna, así que funciona sin conexión y se ve un poco distinta en Windows, macOS y Linux.

Si buscas otra cosa

Pandoc resuelve lo que aquí queda fuera y mucho más: pandoc in.md -o out.html --mathjax --standalone --toc renderiza bien las fórmulas, genera un índice y acepta una plantilla para que el resultado coincida con tu propio sitio. También convierte desde y hacia unos cuarenta formatos más, por eso vale la pena instalarlo una vez.

Para un sitio web, y no un archivo suelto, usa un generador en lugar de convertir las páginas una por una. Hugo, Eleventy, Jekyll y MkDocs convierten una carpeta de Markdown en un sitio con navegación, búsqueda y un estilo uniforme, y lo reconstruyen cada vez que cambia el origen, que es el verdadero trabajo cuando hay más de un documento.