Vista previa de Markdown

Qué Markdown, y por qué se sanea el HTML

Markdown es una familia y no una sola especificación, y el dialecto que se usa aquí es el conjunto ampliamente aceptado de GitHub: encabezados, énfasis, listas, enlaces, imágenes, citas, tablas, bloques de código delimitados con resaltado de sintaxis, listas de tareas, tachado, notas al pie y enlaces automáticos. Es lo que escribe casi todo el mundo y lo que contiene un README. Los dialectos más exóticos y los plugins personalizados que agrega un sitio concreto (bloques de aviso, shortcodes, plantillas) no se admiten, así que un documento escrito para un generador específico puede mostrar parte de su sintaxis de forma literal.

El HTML sin procesar se muestra, pero antes se sanea, y esta es la parte que vale la pena entender. Markdown permite HTML a propósito, lo que significa que un archivo Markdown de cualquier origen puede contener una etiqueta script, un controlador de eventos en línea, un iframe o un enlace javascript:. Mostrarlo tal cual ejecutaría el código de un desconocido en tu sesión solo porque pegaste su README para echarle un vistazo. Todo lo ejecutable se elimina antes de mostrar nada, así que el formato se conserva y el código no.

Es una lección general, no un detalle de esta página. Cualquier sistema que muestre Markdown aportado por usuarios (un cuadro de comentarios, una wiki, un ticket de soporte) está mostrando HTML aportado por usuarios salvo que lo sanee, y “es solo Markdown” es la forma en que eso se pasa por alto. Convertir el Markdown no es una barrera de seguridad; el paso de saneamiento sí lo es.

Lo que obtienes es una vista previa del contenido, no de un sitio en particular. GitHub, GitLab y un generador de documentación aplican cada uno su propia hoja de estilos, sus anclas de encabezado y sus extensiones, así que el mismo archivo se ve distinto en cada uno: la estructura que se muestra aquí es aquello en lo que todos coinciden. No se descarga nada, así que las imágenes referenciadas por una dirección web solo se cargan si ese servidor lo permite, y las rutas relativas a archivos de un repositorio no se pueden resolver en absoluto.

Si buscas otra cosa

Para un README que estás escribiendo de verdad, revisa la vista previa donde va a estar publicado. El propio editor de GitHub muestra la vista previa con su renderizado exacto, sus extensiones y sus anclas, y GitHub CLI (gh markdown-preview) lo hace en local con el mismo renderizador. Para documentación, el propio generador (MkDocs, Docusaurus, Hugo) tiene una vista previa que se recarga en vivo y muestra el estilo y la navegación reales, que es lo que verá el lector.

Para editar, y no solo revisar, un editor de Markdown con panel en vivo (Obsidian, Typora, VS Code con su vista previa integrada) es mejor que pegar el texto en una página cada vez, porque la vista previa se actualiza mientras escribes y el archivo se queda donde está. Esta página es para leer el Markdown de otra persona o para echar un vistazo rápido a algo que te enviaron.