Markdown se ha convertido en el formato por defecto de la documentación técnica: README, wikis, tickets, notas de versión y buena parte de los blogs estáticos se escriben en él porque es legible en texto plano y se convierte a HTML sin ambigüedad. Este previsualizador renderiza en tiempo real mientras escribes, sin subir nada a ningún servidor, para que compruebes el resultado exacto antes de pegarlo en GitHub, GitLab o tu generador de sitios.
CommonMark, GFM y por qué el mismo texto se ve distinto
El Markdown original de 2004 dejó muchos casos sin especificar, así que cada implementación resolvió a su manera. CommonMark es la especificación que fijó el comportamiento exacto (anidamiento de listas, líneas en blanco, énfasis intra-palabra) y es la base de casi todos los renderizadores modernos. GitHub Flavored Markdown añade encima tablas, listas de tareas, tachado, autoenlaces y bloques de código con lenguaje. Por eso una tabla que se ve perfecta en GitHub aparece como texto plano en un renderizador estrictamente CommonMark: no es un error, es una extensión.
Sintaxis que conviene dominar
Encabezados con almohadillas (deja siempre un espacio tras #), listas con - para no confundir con el énfasis, código en línea con acentos graves y bloques con tres acentos más el lenguaje para el resaltado. Los enlaces de referencia ([texto][ref] con la definición al final) mantienen legible un documento con muchas URLs. Para un salto de línea dentro del mismo párrafo hacen falta dos espacios al final o una barra invertida: el error más común es esperar que un simple Enter rompa la línea, porque no lo hace. Las citas anidadas se encadenan con varios > y admiten cualquier otro bloque dentro.
Tablas legibles y sus límites
Las tablas de GFM se alinean con dos puntos en la fila separadora: :--- a la izquierda, ---: a la derecha y :---: centrada. No es necesario que las columnas cuadren visualmente en el fuente, aunque ayuda a mantenerlo. Lo que Markdown no ofrece es fusión de celdas, filas de cabecera múltiples ni celdas con varios párrafos; cuando necesitas eso, la salida honesta es escribir HTML directamente, que casi todos los renderizadores aceptan intercalado. Para tablas de datos largas, plantéate enlazar un CSV y convertirlo con el conversor CSV ↔ JSON en lugar de incrustarlo.
Markdown y seguridad: HTML incrustado
La especificación permite HTML en línea, y ahí está el riesgo: si tu aplicación renderiza Markdown escrito por usuarios y no sanea la salida, un <img src=x onerror=...> se convierte en XSS almacenado. La defensa correcta no es filtrar el Markdown de entrada con expresiones regulares, sino sanear el HTML resultante con una librería específica (DOMPurify en el navegador, bleach en Python) y una lista blanca de etiquetas y atributos. Este previsualizador escapa el HTML en lugar de ejecutarlo, y la herramienta de codificación HTML del sitio te permite ver cómo queda cualquier fragmento escapado.
Documentación que se mantiene sola
Un README útil sigue un orden previsible: qué hace el proyecto en una frase, requisitos, instalación copiable, ejemplo mínimo funcionando, configuración y licencia. Los bloques de código deben poder pegarse tal cual, sin el prompt $ delante, porque quien los copie arrastrará también el símbolo. Los enlaces relativos entre ficheros del repositorio sobreviven a los forks; los absolutos no. Y las capturas conviene guardarlas en una carpeta docs/ del propio repositorio, no en un servicio externo que caducará.
De Markdown a otros formatos
Pandoc convierte Markdown a PDF, DOCX, EPUB o LaTeX con un solo comando y es el camino estándar cuando la documentación debe entregarse en formato ofimático. Los generadores estáticos (Hugo, Astro, MkDocs) añaden front matter YAML al principio del fichero para metadatos como título, fecha y etiquetas; ese bloque no forma parte de Markdown y debe delimitarse con tres guiones. Si necesitas comprobar que el YAML del front matter es válido antes de publicar, el conversor JSON ↔ YAML del sitio te lo verifica en un segundo.
Casos de uso comunes
- Escribir un README y ver el resultado exacto antes de hacer commit.
- Redactar notas de versión con tablas y listas de tareas.
- Comprobar cómo queda una respuesta larga antes de pegarla en un ticket.
- Preparar documentación para un sitio estático con front matter.
- Convertir apuntes en texto plano a HTML limpio.
Buenas prácticas
- Deja siempre un espacio tras `#` y una línea en blanco antes de cada lista o bloque.
- Indica el lenguaje en los bloques de código para activar el resaltado.
- Usa enlaces relativos dentro del repositorio para que sobrevivan a los forks.
- Sanea el HTML resultante si renderizas Markdown escrito por usuarios.