Markdown

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero: escribes texto plano con unos pocos signos de puntuación, como # para un encabezado o * para énfasis, y un conversor lo transforma en HTML. John Gruber lo publicó en 2004 con la ayuda de Aaron Swartz, con el objetivo de que fuera lo más legible posible incluso antes de convertirlo. Los archivos suelen acabar en .md.

Cómo funciona Markdown

Un analizador lee el texto y genera HTML. El mismo origen puede alimentar una página web, un README o un sitio de documentación.

• # Título se convierte en encabezado, con más # se obtienen niveles inferiores.
• **negrita** y *cursiva* marcan el énfasis.
• - elemento inicia una lista con viñetas y 1. elemento una numerada.
• [texto](https://example.com) crea un enlace y ![alt](imagen.png) una imagen.
• Las comillas invertidas envuelven código en línea y tres de ellas delimitan un bloque de código.

Variantes y especificación

La descripción original de Gruber dejaba muchos casos abiertos, como cuánta sangría necesita una sublista, de modo que las implementaciones mostraban el mismo archivo de forma distinta. La especificación CommonMark (versión 0.31.2, enero de 2024) define la sintaxis sin ambigüedad e incluye ejemplos que sirven de pruebas. GitHub Flavored Markdown es un superconjunto estricto de CommonMark que añade tablas, listas de tareas, tachado y autoenlaces ampliados. Comprueba qué variante usa tu herramienta.

Ejemplo

Un README puede empezar con # Payments API, una breve descripción, una lista de endpoints y un bloque de código con una petición de ejemplo. En un repositorio se muestra como página con formato. En un generador de sitios estáticos (véase generación de sitios estáticos), el mismo archivo se convierte en página web durante la compilación.

Errores habituales

• Olvidar la línea en blanco antes de una lista o encabezado, que muchos analizadores necesitan.
• Usar tablas o listas de tareas suponiendo que todos los renderizadores las admiten.
• Saltarse niveles de encabezado, lo que perjudica el esquema y la accesibilidad.
• Incluir Markdown no fiable sin sanear el HTML que genera.
• Usar Markdown para maquetación que no puede expresar, cuando el texto enriquecido o el HTML encajan mejor.

Markdown en documentación y pruebas

Los equipos guardan documentación, changelogs y planes de prueba en Markdown junto al código, de modo que pasan por la misma revisión y CI. Las piezas reutilizables encajan bien en un bloque de contenido. LoadFocus publica sus guías de producto en su documentación. Para pipelines que ejecutan comprobaciones en cada commit, consulta la guía de GitHub Actions (en inglés).

Preguntas frecuentes sobre Markdown

¿Para qué se usa Markdown?

Para escribir READMEs, documentación, artículos de blog, notas y mensajes de chat en texto plano que se convierte en HTML. Gusta porque el origen sigue siendo legible y encaja bien con el control de versiones.

¿Qué diferencia hay entre Markdown y HTML?

HTML describe una página con etiquetas y cubre todo lo que ofrece la web. Markdown es una sintaxis más corta para estructuras habituales como encabezados, listas y enlaces, y se convierte en HTML. A menudo se puede mezclar HTML directo.

¿Qué es CommonMark?

Una especificación que define la sintaxis de Markdown sin ambigüedad, con ejemplos que sirven de pruebas de conformidad. Nació porque la descripción original dejaba muchos casos sin definir.

¿Qué es GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) es un superconjunto estricto de CommonMark. Añade tablas, listas de tareas, tachado y autoenlaces ampliados.

¿Cómo convierto Markdown a HTML?

Con un analizador de Markdown o una herramienta que lo incluya, como un generador de sitios estáticos, la vista previa de un editor o un conversor de línea de comandos. Sanea el resultado si el Markdown viene de usuarios.