Formatos de archivo
¿Qué es Markdown? Sintaxis, CommonMark y GFM
Markdown es un lenguaje de marcado ligero que añade títulos, listas y enlaces al texto plano con unos pocos símbolos. Repasamos su historia, sus normas y qué se conserva al convertir archivos MD a Word o PDF.
Autor: Hemen Dönüştür Editör EkibiPublicado: 8 min de lectura
Piensa en el README de un proyecto de software, en las listas con títulos de una aplicación de notas o en las palabras que pones en negrita con asteriscos en una aplicación de mensajería. Detrás de todo ello está la misma idea: Markdown. Markdown es un lenguaje de marcado ligero que permite definir títulos, listas, enlaces y tablas añadiendo unos pocos símbolos sencillos al texto plano. El archivo sigue siendo legible en cualquier editor de texto y, aun así, se puede convertir en una página HTML limpia, un documento de Word o un PDF cuando lo necesites. En este artículo verás cómo surgió Markdown, su sintaxis básica, las diferencias entre CommonMark y GitHub Flavored Markdown y qué vigilar al convertir archivos MD.
¿Qué es Markdown?
Markdown es a la vez un conjunto de convenciones de escritura y el nombre habitual de las herramientas que convierten en HTML el texto escrito con ellas. Los archivos suelen guardarse con la extensión .md o .markdown. Según su creador, John Gruber, el objetivo principal del diseño es la legibilidad: un documento Markdown debería poder publicarse tal cual, como texto plano, sin que parezca marcado con etiquetas o instrucciones de formato. Donde HTML necesita <strong>importante</strong>, Markdown usa **importante**, e incluso la versión sin procesar se lee con naturalidad.
Un poco de historia
John Gruber creó Markdown en 2004, con Aaron Swartz como interlocutor para contrastar sus ideas. La sintaxis se inspiró en las convenciones del correo electrónico en texto plano (asteriscos para el énfasis, guiones para las listas) y en lenguajes de marcado anteriores como setext y Textile. La versión 1.0.1 de Markdown.pl, el script de Perl que Gruber publicó en su sitio Daring Fireball, tiene fecha del 17 de diciembre de 2004.
Sin embargo, la descripción de Gruber era una explicación mediante ejemplos y no una especificación formal. Los casos ambiguos (listas anidadas, bloques de código con sangría, mezcla con HTML) llevaron a cada implementación a tomar sus propias decisiones, y el mismo texto empezó a producir resultados distintos en herramientas distintas. Hubo dos grandes respuestas:
- CommonMark (2014): una especificación dirigida por John MacFarlane que define Markdown sin ambigüedades y lo hace verificable con cientos de ejemplos. Las primeras versiones aparecieron en otoño de 2014; la versión actual es la 0.31.2, del 28 de enero de 2024. La especificación todavía no se ha declarado 1.0.
- GitHub Flavored Markdown (GFM, 2017): la especificación formal de GitHub construida sobre CommonMark. Añade extensiones como tablas, listas de tareas, tachado, enlaces automáticos ampliados y, por seguridad, el filtrado de ciertas etiquetas HTML sin procesar. La última especificación publicada es la 0.29-gfm, del 6 de abril de 2019.
Markdown también obtuvo reconocimiento en la infraestructura de internet: la RFC 7763, publicada en marzo de 2016, registró el tipo de medio (tipo MIME) text/markdown con un parámetro opcional variant que indica qué variante de Markdown pretendía usar el autor.
Principales variantes de Markdown
Además de CommonMark y GFM existen otras variantes muy extendidas. La RFC 7764, publicada junto con la RFC 7763, registró varias de ellas y ofreció pautas de uso:
- Markdown Extra: una de las primeras extensiones, que añadió notas al pie, listas de definiciones y tablas.
- MultiMarkdown: una variante orientada a la escritura académica, con metadatos, citas y referencias cruzadas.
- Pandoc Markdown: la variante que usa el conversor Pandoc, con muchas extensiones para escribir libros y artículos.
Una regla práctica: si tu documento solo usa títulos, listas, enlaces, código y tablas sencillas, se verá igual casi en todas partes. Si dependes de notas al pie, listas de definiciones o tipos de bloque especiales, comprueba qué variante admite el entorno de destino.
Sintaxis básica
La parte de Markdown que necesitas en el día a día se aprende en unos minutos:
# Título de nivel uno
## Título de nivel dos
Este párrafo tiene **negrita**, *cursiva* y `código`.
- Lista con viñetas
- Segundo elemento
- Subelemento con sangría
1. Lista numerada
2. Segundo paso
[Texto del enlace](https://example.com)
> Cita
```
Bloque de código de varias líneas
```Las tablas y las listas de tareas, añadidas por GFM, tienen este aspecto:
| Formato | Extensión |
|---------|-----------|
| Markdown | .md |
| Texto plano | .txt |
- [x] Escribir el borrador
- [ ] RevisarloLos párrafos se separan con líneas en blanco. La mayoría de las implementaciones tratan un salto de línea simple como parte del mismo párrafo; para forzar un salto de línea, termina la línea con dos espacios. También puedes escribir HTML directamente dentro de Markdown. CommonMark lo permite, aunque entornos como GFM bloquean ciertas etiquetas por seguridad.
¿Dónde se usa Markdown?
- Desarrollo de software: README, registros de cambios y guías de contribución, además de incidencias y comentarios de revisión de código en plataformas como GitHub y GitLab.
- Documentación técnica: generadores de sitios estáticos que construyen sitios web a partir de archivos Markdown.
- Toma de notas: muchas aplicaciones de notas guardan o exportan las notas en Markdown.
- Plataformas de chat y comunidades: plataformas como Reddit y Discord usan variantes de Markdown.
- Escritura y edición: generar HTML, PDF, DOCX y EPUB a partir de un único original en Markdown con herramientas como Pandoc.
- Herramientas de IA: los asistentes de IA basados en chat suelen dar formato a sus respuestas en Markdown.
Ventajas y desventajas
| Ventajas | Desventajas |
|---|---|
| Legible incluso sin procesar | Las variantes se comportan de forma distinta |
| Texto plano: pequeño, portátil y cómodo para el control de versiones | Sin fuentes, colores ni maquetación de página |
| Se convierte fácilmente a HTML, PDF y Word | Sin tablas complejas (celdas combinadas) |
| Se aprende en minutos | Las imágenes van en archivos aparte |
| No depende de ningún programa | Los errores de espacios y sangría cambian el resultado |
¿Qué programas abren Markdown?
Como Markdown es texto plano, se abre en cualquier editor de texto, incluidos el Bloc de notas y TextEdit. Para ver una vista previa con formato puedes usar la vista previa de Markdown integrada en Visual Studio Code o editores específicos como Obsidian y Typora. GitHub y GitLab muestran automáticamente con formato los archivos .md de los repositorios. Word, en cambio, no abre Markdown como texto con formato, así que primero tienes que convertir el archivo.
Problemas habituales y cómo resolverlos
Una lista o un título no se muestran bien
CommonMark exige un espacio después del marcador de título: ## Título, no ##Título. Una lista que va después de un párrafo también suele necesitar una línea en blanco entre ambos para mostrarse correctamente.
Las líneas se juntan
Un salto de línea simple no divide un párrafo. Deja una línea en blanco para empezar un párrafo nuevo, o termina la línea con dos espacios para hacer un salto dentro del párrafo.
Una tabla funciona en una plataforma pero no en otra
Las tablas no forman parte del Markdown original de Gruber ni del núcleo de CommonMark; vienen de extensiones como GFM. Comprueba qué variante admite la plataforma de destino.
Un párrafo que empieza por un número se convierte en lista numerada
Una línea como «2024. fue un año intenso» empieza con dígitos y un punto, así que puede interpretarse como una lista. Escapa el punto con una barra invertida (2024\.) para evitarlo.
Consejos para convertir archivos Markdown
En nuestro conversor, los archivos Markdown se suben a nuestro servidor y se eliminan en un plazo de 30 minutos. Para leerlos usamos la biblioteca Markdig con CommonMark y extensiones al estilo de GitHub (tablas, listas de tareas, notas al pie, enlaces automáticos).
- Markdown a PDF y Markdown a Word conservan los títulos, las listas, los bloques de código, las citas y las tablas con bordes. Las casillas de las listas de tareas se convierten en los caracteres ☑ y ☐ para que sigan viéndose en Word y PDF. Por defecto, el texto se compone en una fuente con serifa de 12 pt y los bloques de código, en una fuente monoespaciada.
- Markdown a HTML convierte un README en una página web autónoma con la codificación de caracteres declarada.
- En sentido contrario, Word a Markdown, HTML a Markdown y PDF a Markdown generan Markdown compatible con GitHub: se conservan los títulos, la negrita y la cursiva, las listas, las tablas, los enlaces, los bloques de código y las citas; se descartan las fuentes, los colores y la maquetación de página. En las tablas sin fila de encabezado, la primera fila pasa a ser el encabezado, porque las tablas GFM lo exigen. Los párrafos normales que empiezan por un número, como «1. Cláusula», se escapan para que no se conviertan en listas por accidente. El archivo se guarda como UTF-8 sin BOM.
Preguntas frecuentes
¿Cómo abro un archivo MD?
Lo abre cualquier editor de texto. Para verlo con formato, usa la vista previa de Visual Studio Code o un editor de Markdown; si quieres leerlo en Word, conviértelo a DOCX.
¿Qué diferencia hay entre CommonMark y GitHub Flavored Markdown?
CommonMark define la sintaxis básica de Markdown con reglas precisas. GFM es un superconjunto que añade extensiones sobre CommonMark, como tablas, listas de tareas, tachado y enlaces automáticos ampliados.
¿Puedo hacer tablas en Markdown?
Sí, con extensiones como GFM puedes escribir tablas sencillas con barras verticales y guiones. Para estructuras complejas, como celdas combinadas, usa una tabla HTML o prepara el documento en Word.
¿Qué diferencia hay entre Markdown y HTML?
Markdown es un formato de escritura más sencillo, pensado para convertirse en HTML. No puede expresar todo lo que expresa HTML, pero su forma sin procesar es mucho más legible. Aun así, puedes escribir HTML dentro de Markdown cuando lo necesites.
¿Markdown tiene una norma oficial?
La descripción original de Gruber no es una especificación formal. La definición precisa más aceptada hoy es CommonMark, y el tipo de medio text/markdown lo registró la RFC 7763 en marzo de 2016.
Fuentes
- John Gruber, Daring Fireball: Markdown
- CommonMark Spec (historial de versiones)
- GitHub Flavored Markdown Spec
- IETF RFC 7763: The text/markdown Media Type (marzo de 2016)
- IETF RFC 7764: Guidance on Markdown
- Wikipedia: Markdown (historia, fuente secundaria)
- Markdig: procesador de Markdown compatible con CommonMark para .NET
