Guía Markdown: primeros pasos

Markdown es una sintaxis de formato en texto plano que convierte símbolos escritos en documentos estructurados, y su núcleo se aprende en unos 10 minutos. John Gruber lo publicó en marzo de 2004 con aportaciones de Aaron Swartz, y 22 años después da formato a los ficheros README de GitHub, a las notas de Obsidian y a las publicaciones de Reddit. Todo el sistema tiene dos partes: un fichero de texto guardado con extensión .md y un procesador que convierte ese texto a HTML. Todo lo que viene a continuación se apoya en esas dos partes.

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero creado en 2004 que añade instrucciones de formato al texto plano mediante caracteres visibles como #, * y >. Una # al principio de una línea crea un encabezado. Dos asteriscos alrededor de una palabra la ponen en negrita. Un guion inicia una viñeta. La versión original era un único script en Perl, Markdown.pl, publicado en Daring Fireball, la web de Gruber.

Los lenguajes de marcado más pesados, HTML y LaTeX entre ellos, envuelven el contenido en etiquetas y comandos que ensucian el fichero original. Markdown tomó el camino contrario. Gruber diseñó la sintaxis con un objetivo: que un fichero Markdown se lea con claridad como texto plano antes de cualquier conversión. La línea ## Precios es un encabezado evidente incluso para alguien que nunca ha oído hablar de Markdown. Esa legibilidad explica que el formato se extendiera desde los blogs en 2004 a GitHub en 2008, a Stack Overflow en 2010 y a aplicaciones de notas como Obsidian y Joplin a lo largo de la década de 2010.

En qué se diferencia Markdown de los editores WYSIWYG

Un editor WYSIWYG como Microsoft Word o Google Docs aplica el formato con botones de la barra de herramientas y oculta las instrucciones; Markdown mantiene cada instrucción visible como caracteres dentro del fichero. WYSIWYG significa "lo que ves es lo que obtienes". En Word seleccionas una frase y haces clic en el botón de negrita, y el fichero guarda esa decisión en un XML binario que nunca ves. En Markdown escribes **fecha de lanzamiento** y los dos pares de asteriscos son el formato.

La diferencia se nota al guardar. Un fichero .docx se abre correctamente en una lista corta de programas, con Word, LibreOffice y Pages a la cabeza. Un fichero Markdown se abre en cualquier editor de texto publicado desde los años 70, desde el Bloc de notas hasta vim o VS Code. Muchos editores de Markdown cierran la brecha visual con una vista previa en pantalla dividida: sintaxis en bruto en el panel izquierdo, resultado renderizado en el derecho, actualizado con cada pulsación. Obtienes la respuesta inmediata de Word con la transparencia del texto plano.

Por qué la gente usa Markdown

Quienes escriben eligen Markdown por cuatro razones prácticas: portabilidad, independencia de plataforma, resistencia al paso del tiempo y alcance. Las cuatro nacen de su base de texto plano.

• Portabilidad. Un fichero Markdown pasa de una aplicación a otra sin conversión. Redacta un artículo en iA Writer, edítalo en VS Code y publícalo con Ghost. El fichero nunca cambia de forma. Los formatos propietarios como .docx y .pages encierran el contenido en el ecosistema de un único proveedor.
• Independencia de plataforma. Markdown funciona igual en Windows 11, macOS, Linux, iOS y Android. El fichero es texto UTF-8, así que una nota escrita en el móvil en 2026 se abre byte a byte idéntica en el ordenador.
• Resistencia al paso del tiempo. El software muere; los ficheros de texto sobreviven. WordPerfect dominaba el procesamiento de textos en 1990 y hoy recuperar sus ficheros antiguos es todo un proyecto. Un fichero Markdown de 2004 sigue abriéndose en menos de un segundo, algo que importa en tesis, contratos y manuscritos de libros con horizontes de 20 años.
• Alcance. Plataformas como GitHub, GitLab, Reddit, Discord, Notion y Slack aceptan Markdown. Aprende la sintaxis una vez y te sirve en todas ellas.

Cómo funciona el procesamiento de Markdown

Markdown se convierte en un documento con formato mediante una cadena de 4 pasos: escribes un fichero .md, un procesador lo analiza, el procesador genera HTML y un navegador renderiza ese HTML. El procesador, también llamado parser o implementación, es el motor que hay dentro de cada aplicación de Markdown. Entre los procesadores populares están markdown-it, marked, cmark y Pandoc, y cmark convierte un documento típico en menos de 10 milisegundos.

Cada herramienta expone una parte distinta de esta cadena. Un editor online con vista previa en vivo ejecuta los pasos 2 a 4 de forma invisible con cada pulsación. Un generador de sitios estáticos como Hugo ejecuta la misma cadena sobre cientos de ficheros con un solo comando de compilación. La cadena en sí nunca cambia, y el HTML resultante se combina con cualquier hoja de estilos CSS o se convierte después a PDF, EPUB o .docx con una herramienta como Pandoc.

¿Para qué se usa Markdown?

Markdown cubre siete tareas habituales: webs, notas, documentos, libros, presentaciones, correo electrónico y documentación técnica. La misma sintaxis de 10 minutos sirve para las siete.

Webs

Los generadores de sitios estáticos como Hugo, Jekyll y Eleventy construyen webs completas a partir de carpetas de ficheros Markdown. Jekyll, publicado en 2008, impulsa GitHub Pages y su alojamiento gratuito. Las plataformas de contenido también aceptan Markdown: Ghost tiene un editor Markdown nativo y WordPress lo admite a través de su editor de bloques. Una entrada de blog es un solo fichero .md, y los sistemas de control de versiones como Git registran cada edición que le haces.

Notas y documentos

Aplicaciones de notas como Obsidian, Joplin, Bear y Simplenote guardan cada nota como Markdown. Solo Obsidian almacena cada bóveda como una carpeta de ficheros .md en tu propio disco, de modo que una colección de 5.000 notas sigue siendo buscable con herramientas estándar. Para documentos sueltos, cartas, actas de reuniones y trabajos de clase, un editor Markdown exporta directamente a PDF o HTML, y ese PDF se imprime, se adjunta a un correo o se sube a cualquier sitio.

Libros y presentaciones

Leanpub convierte una carpeta de ficheros Markdown en un ebook terminado en formatos PDF y EPUB, y Pandoc hace lo mismo desde la línea de comandos. Hay autores que han publicado novelas completas y libros técnicos de 300 páginas así. Para diapositivas, herramientas como Marp y Remark transforman un fichero Markdown en una presentación, con un separador --- por diapositiva, mucho más rápido de revisar que un PowerPoint con 40 diapositivas formateadas a mano.

Correo electrónico y documentación técnica

Extensiones de navegador como Markdown Here convierten Markdown en correo HTML con formato dentro de Gmail y otros clientes de webmail. La documentación es el terreno natural de Markdown: GitHub renderiza un README.md en la parte superior de cada repositorio, y generadores como MkDocs, Docusaurus y Read the Docs construyen sitios de documentación completos a partir de ficheros .md. Docusaurus, publicado por Meta en 2017, añade versionado y búsqueda sobre páginas Markdown normales.

Flavors de Markdown: CommonMark y GFM

Un flavor de Markdown es una variante concreta de la sintaxis, y las dos que más importan son CommonMark, especificado en 2014, y GitHub Flavored Markdown, especificado en 2017. La versión de 2004 de Gruber dejó casos límite sin definir, como la sangría de las listas anidadas, así que los primeros procesadores discrepaban en el resultado. El mismo fichero se renderizaba distinto según la herramienta.

CommonMark lo arregló. Publicada en septiembre de 2014 por un grupo de trabajo en el que participaron John MacFarlane y Jeff Atwood, la especificación CommonMark fija cada regla de análisis con más de 600 casos de prueba. Stack Overflow migró su renderizado a CommonMark en junio de 2020.

GitHub Flavored Markdown, o GFM, es un superconjunto estricto de CommonMark que GitHub formalizó en marzo de 2017. Añade cinco extensiones: tablas, listas de tareas, tachado, autoenlaces y bloques de código delimitados con etiqueta de lenguaje. Cuando la página de un producto dice que "admite Markdown", comprueba a qué flavor se refiere, porque una tabla GFM se renderiza como simples barras verticales en una herramienta que solo soporte CommonMark. GFM es la opción más segura en 2026, y es el flavor que renderiza el editor de este sitio.

Cómo empezar a escribir en Markdown hoy

Abre un editor de Markdown en el navegador, escribe una # seguida de un título y ya has escrito tu primer Markdown; no hay nada que instalar ni cuenta que crear. Un editor de doble panel muestra el resultado renderizado mientras escribes, que es el circuito de respuesta más rápido para aprender la sintaxis.

Empieza por los cinco elementos más frecuentes: # para encabezados, **negrita**, *cursiva*, - para listas y [texto](url) para enlaces. Esos cinco cubren aproximadamente el 90% del formato cotidiano. Practica reescribiendo algo real, una nota de reunión o una lista de tareas, y guarda el resultado como fichero .md. A partir de ahí, la guía de sintaxis básica cubre los 9 elementos fundamentales, y la guía de sintaxis extendida añade tablas GFM, notas al pie y listas de tareas.

Preguntas frecuentes

¿Necesito instalar software para escribir en Markdown?

Con un navegador web basta; un editor de Markdown online se encarga de la escritura, la vista previa y la exportación sin instalar nada. Las aplicaciones de escritorio como Obsidian, iA Writer y VS Code añaden acceso sin conexión y gestión de ficheros locales cuando las necesites.

¿Qué extensión de fichero usa un fichero Markdown?

Los ficheros Markdown usan la extensión .md, con .markdown como alternativa menos común. Ambas contienen texto plano idéntico, y todos los procesadores de Markdown, de cmark a Pandoc, aceptan cualquiera de las dos.

¿Cuánto se tarda en aprender Markdown?

Los cinco elementos básicos se aprenden en unos 10 minutos, y la sintaxis básica completa de 9 elementos cabe en una sola sesión. Las extensiones GFM, como tablas y listas de tareas, suman otros 15 minutos. Compáralo con LaTeX, donde dar formato con soltura lleva semanas.

¿Cuál es la diferencia entre CommonMark y GFM?

CommonMark es la especificación base de 2014 que estandariza el análisis del Markdown básico, y GFM es el superconjunto de GitHub de 2017 que añade tablas, listas de tareas, tachado, autoenlaces y bloques de código delimitados. Todo documento CommonMark válido también es GFM válido, así que escribir en GFM es la elección práctica.