Markdown, el lenguaje de formato ligero explicado a fondo

Seguidores Online » Redes Sociales » Markdown, el lenguaje de formato ligero explicado a fondo

Markdown se ha convertido en el lenguaje de formato ligero de referencia para escribir texto que termine publicado en la web, ya sea una documentación técnica, un README en GitHub o un simple apunte personal. Permite dar estructura y estilo al contenido usando solo caracteres de teclado normales, sin necesidad de pelearte con el HTML a mano.

La gracia de Markdown es que el texto sigue siendo perfectamente legible incluso sin “renderizar”: puedes abrir el archivo en cualquier editor plano, ver encabezados, listas, citas o código y entenderlo sin esfuerzo. Y cuando lo procesas con una herramienta compatible (editores, plataformas web, generadores de sitios estáticos…), se transforma en HTML bien formado listo para publicarse.

Qué es Markdown y por qué se usa tanto

Markdown es un lenguaje de marcado ligero basado en unas cuantas reglas muy sencillas. La idea es que, con símbolos como almohadillas, asteriscos o guiones, puedas indicar qué partes del texto son títulos, listas, negritas, citas, etc. A diferencia de HTML o XML, la sintaxis es mínima, poco ruidosa y muy cercana al texto plano de toda la vida.

Originalmente, John Gruber lo diseñó para que fuera trivial convertir un texto en Markdown en HTML válido, sin que el autor tuviera que preocuparse por etiquetas de apertura y cierre, anidaciones raras ni errores de sintaxis. Con el tiempo, se ha convertido en un estándar de facto para documentación técnica, blogs de desarrolladores, manuales internos y, en general, cualquier texto que quieras escribir rápido y mantener legible.

En la práctica, cuando escribes Markdown estás definiendo una especie de contrato: “si pongo tal símbolo, interprétalo como formato”. Exactamente igual que cuando en un chat acuerdas con alguien que *así* es cursiva y así es negrita. Luego un programa se encarga de traducir esas reglas a HTML, PDF u otros formatos.

Hoy en día lo usan plataformas tan variadas como GitHub, GitLab, MDN Web Docs, Adobe Docs o infinidad de blogs estáticos con motores como Jekyll, Hugo o Astro. Para el usuario, la ventaja es doble: puede editar con cualquier editor de texto plano y, a la vez, obtener una salida web profesional con muy poco esfuerzo.

Breve historia y variantes de Markdown

Markdown nació en 2004, cuando John Gruber quiso simplificar el proceso de escribir HTML. La primera especificación era muy básica, pero suficiente para encabezados, listas, enlaces, énfasis y poco más. A partir de ahí fueron surgiendo extensiones para cubrir necesidades reales: tablas, notas al margen, definiciones, etc.

Una de las primeras ampliaciones fue Markdown Extra, que añadió soporte para tablas y otros elementos más avanzados. Más tarde aparecieron variaciones muy populares como GitHub Flavored Markdown (GFM), utilizada en GitHub y muchas otras herramientas, o CommonMark, que intenta estandarizar el lenguaje para que no haya comportamientos distintos según el procesador.

El lado bueno de esta evolución es que Markdown ha ganado potencia y flexibilidad. El lado malo es que no todos los sabores se comportan igual: puede que una tabla o una lista de definiciones que funcionan en un sitio no se vean igual en otro. Por eso proyectos grandes, como MDN Web Docs o la documentación de Adobe, definen sus propias pautas internas sobre qué sintaxis concreta se admite y qué extensiones se usan.

A pesar de estas diferencias, la base es la misma: párrafos, encabezados, listas, enlaces, imágenes y código funcionan prácticamente igual en todos los procesadores, lo que hace que aprender Markdown una sola vez te sirva en casi cualquier contexto.

Usos principales de Markdown en la práctica

Uno de los grandes motivos de su popularidad es que Markdown encaja muy bien con la forma real de trabajar de quienes escriben mucho texto técnico o para la web. No necesitas un editor pesado, ni menús infinitos, ni botones de formato: todo se hace escribiendo.

En desarrollo de software, por ejemplo, es casi obligatorio: los archivos README.md de los repositorios suelen estar en Markdown, al igual que la documentación de proyectos, guías de estilo o changelogs. Plataformas como GitHub soportan GitHub Flavored Markdown, añadiendo extras como tablas, listas de tareas o menciones.

También es muy habitual en blogging y generación de sitios estáticos. Herramientas como Jekyll, Hugo o Astro permiten escribir las entradas del blog en archivos .md, que luego se convierten a HTML al generar la web. Esto facilita mantener el contenido versionado con Git y separado del diseño.

Para la toma de notas personales, Markdown brilla porque permite mezclar texto libre con un mínimo de estructura. Aplicaciones como Obsidian, Notion o la mejor aplicación de notas para Android soportan Markdown (o una variante) y facilitan buscar, enlazar y reorganizar la información con rapidez.

En entornos más académicos o profesionales, Markdown se combina con herramientas como Pandoc para, a partir de un único fichero fuente, generar HTML, PDF o incluso presentaciones de diapositivas. Esta versatilidad lo convierte en una opción muy cómoda para manuales, informes o documentación que deba distribuirse en varios formatos.

Sintaxis básica de Markdown: cómo se estructura el texto

La sintaxis original de Gruber define un núcleo de elementos que casi todas las implementaciones respetan. Si dominas estos básicos, ya puedes escribir documentos muy completos.

Párrafos y saltos de línea

En Markdown, un párrafo es simplemente uno o varios renglones de texto seguidos. Para separar un párrafo de otro basta con dejar una línea en blanco entre medias. Al procesar el documento, el motor de Markdown envuelve cada bloque en etiquetas <p> y </p> de HTML.

Si lo que quieres no es empezar un párrafo nuevo, sino forzar un salto de línea dentro del mismo párrafo, existen varias técnicas: la más común es dejar dos o más espacios al final de la línea y pulsar Intro, lo que se traduce en un <br> en HTML. También muchas implementaciones aceptan directamente la etiqueta <br> en la línea, o incluso permiten pulsar Intro sin más, aunque esto último no está estandarizado.

Encabezados

Los títulos se crean anteponiendo el símbolo de almohadilla a la línea correspondiente. El número de almohadillas indica el nivel del encabezado: una para nivel 1, dos para nivel 2, hasta un máximo habitual de seis niveles.

Por ejemplo, una línea que empieza con una almohadilla y un espacio se traducirá a un <h1> en HTML, mientras que tres almohadillas seguidas de un espacio generarán un <h3>. Algunas implementaciones permiten una sintaxis alternativa usando signos de igual y guiones bajo el texto para crear niveles 1 y 2, pero el estilo con almohadillas es el más extendido y compatible.

Texto en negrita y cursiva

Para enfatizar palabras o frases, Markdown utiliza asteriscos o guiones bajos rodeando el texto. Un solo asterisco o guion bajo a cada lado aplica cursiva; dos asteriscos o dos guiones bajos aplican negrita; y tres pueden combinar negrita y cursiva a la vez.

Por ejemplo, escribir una palabra rodeada de un solo asterisco la marcará como cursiva, mientras que hacerlo con dos la resaltará en negrita. En mitad de una palabra, esta técnica también funciona, aunque el uso de guiones bajos dentro de palabras puede ser problemático en algunas implementaciones, por lo que se suele recomendar usar preferentemente asteriscos para evitar sorpresas.

Código en línea y bloques de código

Markdown distingue entre código corto dentro de una frase y fragmentos más largos en bloque. Para marcar código en línea se usan comillas invertidas alrededor del texto. Si el trozo de código incluye comillas invertidas dentro, se duplican las externas o se juega con los espacios para que no haya conflictos.

Cuando lo que quieres es mostrar varias líneas de código, puedes crear un bloque de código de dos maneras clásicas: añadiendo al menos cuatro espacios o una tabulación al principio de cada línea, o usando las llamadas “vallas de código” (tres comillas invertidas en una línea antes y después del bloque). Muchas variantes, como GFM y el Markdown de MDN o Adobe, permiten especificar el lenguaje tras la valla de apertura para activar el resaltado de sintaxis.

Citas en bloque

Las citas se construyen comenzando la línea con el símbolo mayor que seguido de un espacio. Cada línea de la cita mantiene ese marcador y puedes separar párrafos dentro de la cita dejando líneas en blanco que solo contienen el símbolo de cita.

Las citas pueden anidarse añadiendo más símbolos de mayor que al inicio, creando niveles de profundidad. Además, dentro de ellas se admiten casi todos los elementos normales de Markdown: encabezados, listas, fragmentos de código o enlaces, siempre que respetes la sintaxis de la cita en cada línea.

Líneas horizontales

Para insertar una separación visual entre secciones, Markdown permite crear reglas horizontales con tres o más caracteres repetidos: normalmente asteriscos, guiones o guiones bajos. Es importante que esos símbolos estén solos en la línea, sin texto adicional.

Por compatibilidad se recomienda dejar una línea en blanco antes y después de la regla, evitando pegarla a otros elementos de forma que el procesador pueda interpretarla sin ambigüedades.

Listas en Markdown: numeradas, con viñetas y anidadas

Otro pilar del lenguaje es la gestión de listas. Markdown permite tanto listas ordenadas (numeradas) como desordenadas (con viñetas), y casi todas las variantes soportan anidarlas para representar estructuras más complejas.

Listas no ordenadas

Una lista de viñetas se crea iniciando cada elemento con un guion, un signo más o un asterisco seguido de un espacio. Cada línea que siga este patrón se convierte en un ítem de la lista. Aunque el estándar básico permite mezclar estos marcadores dentro de una misma lista, no todos los procesadores lo representan igual, por lo que suele recomendarse mantener un solo tipo de viñeta en cada bloque.

En algunos entornos específicos, como ciertas guías de Adobe o sistemas de tickets, se obliga explícitamente a usar un tipo de viñeta concreto y advierten de no mezclar formatos dentro de la misma lista para evitar problemas de representación.

Listas ordenadas

Las listas numeradas se crean empezando cada ítem con un número, un punto y un espacio. Lo curioso es que, aunque escribas números distintos, muchas implementaciones renumeran automáticamente empezando en 1 y siguiendo en orden. Esto es bastante cómodo cuando reordenas puntos, pero también significa que si necesitas una numeración específica, tendrás que recurrir a HTML o a pegar el texto sin formato.

Algunas variantes aceptan también paréntesis en lugar de puntos tras el número, pero de nuevo no es algo universal. Por eso, cuando se busca máxima compatibilidad, es preferible ceñirse al formato número + punto.

Listas anidadas y contenido dentro de las listas

Markdown permite anidar listas dentro de otras listas mediante sangrías: si un elemento de lista contiene otra lista, se añaden cuatro espacios o una tabulación delante de los ítems anidados. Esto funciona tanto con listas ordenadas como con no ordenadas.

Además de sublistas, dentro de un elemento de lista se pueden incluir párrafos adicionales, citas, imágenes o bloques de código. En esos casos, suele ser necesario dejar una línea en blanco y aplicar la sangría apropiada para que el procesador entienda que ese contenido sigue perteneciendo al mismo punto de la lista.

Enlaces, imágenes y tablas: dar estructura avanzada al contenido

Para que un documento en Markdown sea realmente útil en la web, es fundamental poder insertar enlaces, recursos visuales y tablas. La sintaxis cubre todos estos casos, aunque con algunos matices según la variante que estés usando.

Enlaces básicos e internos

El formato estándar de un enlace en línea consiste en encerrar el texto visible entre corchetes y, a continuación, escribir la URL entre paréntesis. Opcionalmente, se puede añadir un título entre comillas tras la URL, que se mostrará al pasar el ratón por encima en un navegador.

Además, es posible enlazar a secciones dentro de la misma página o de otras páginas añadiendo el símbolo de almohadilla y el identificador correspondiente al final de la URL. Algunos procesadores admiten atajos como escribir directamente la URL rodeada de símbolos mayor y menor, o detectar correos electrónicos para generar enlaces mailto automáticos.

Enlaces por referencia

Junto con los enlaces en línea, muchas implementaciones soportan los llamados enlaces de referencia, que separan el texto del enlace de la URL. El texto enlazado incluye un identificador entre corchetes, y en otra parte del documento se define ese identificador con la URL y, opcionalmente, el título.

Esta técnica mejora la legibilidad de documentos largos llenos de enlaces, ya que las URLs se agrupan como si fueran notas al pie. Sin embargo, no todas las plataformas la permiten: por ejemplo, en el Markdown personalizado de MDN Web Docs se han limitado a aceptar solo enlaces en línea para mantener las cosas simples y predecibles.

Imágenes y combinaciones con enlaces

La inserción de imágenes sigue un patrón muy similar al de los enlaces, con la diferencia de que se antepone un signo de exclamación al comienzo. Entre corchetes se indica el texto alternativo que verá el usuario si la imagen no carga y que además mejora la accesibilidad; entre paréntesis, la URL de la imagen, con un posible título opcional entre comillas.

También puede crearse una imagen que a su vez sea un enlace, envolviendo la sintaxis de la imagen con la de un enlace. De esa forma, al hacer clic en la imagen se abrirá la URL asociada. Algunas plataformas imponen restricciones: determinados sistemas de comentarios o bloques de contenido no admiten imágenes o limitan su uso, por lo que conviene revisar siempre la documentación de la herramienta que estés usando.

Tablas en Markdown y cuándo usar HTML

Las tablas no formaban parte del Markdown original, pero la mayoría de sabores modernos incluyen una sintaxis de tablas “tipo ASCII art”, como GFM o Markdown Extra. Esta sintaxis utiliza barras verticales para separar columnas y una fila de guiones para marcar el encabezado. Es muy cómoda para tablas sencillas con contenido corto en cada celda.

Sin embargo, tiene limitaciones claras: no permite columnas de encabezado, celdas que abarquen varias filas o columnas, ni elementos de bloque complejos dentro de las celdas (como listas o párrafos múltiples) en muchas implementaciones. Proyectos como Adobe recomiendan evitar las tablas si el contenido es demasiado complejo y sustituirlas por encabezados y texto corrido cuando sea posible.

En el caso específico de MDN Web Docs, se establecen reglas adicionales: se fomenta el uso de tablas GFM siempre que la tabla no rebase cierto ancho en caracteres y no requiera funcionalidades avanzadas. Si la tabla es demasiado ancha, compleja o necesita clases y atributos especiales, se pide directamente usar HTML con <table>, <tr>, <th> y <td>, y en algunos casos una clase CSS concreta (como «properties») para tablas de propiedades muy estructuradas.

Extensiones y sabores: Adobe, GitHub, MDN y compañía

Además de la sintaxis base, muchas organizaciones definen “dialectos” propios de Markdown que amplían o ajustan el lenguaje a sus necesidades. Esto es especialmente visible en la documentación técnica de grandes plataformas.

Markdown ampliado en la documentación de Adobe

Los artículos técnicos de Adobe se almacenan en GitHub y se escriben usando una variante GitHub Flavored Markdown combinada con extensiones propietarias. Además de los elementos básicos (párrafos, listas, enlaces, tablas sencillas), su “Adobe Markdown ampliado” añade construcciones para notas, sugerencias, bloques de ayuda, vídeos incrustados o componentes como “Más como esto”.

En estos documentos se abusa de las citas en bloque con el símbolo mayor que como punto de entrada a componentes avanzados: por ejemplo, una nota se marca como un bloque especial precedido de cierto texto, y el sistema de publicación lo transforma en un recuadro visual destacado. También se manejan bloques de código con propiedades ampliadas definidas entre llaves, para ajustar parámetros predeterminados del componente.

Adobe, además, estipula pautas de localización con marcas como UICONTROL o DNL que sirven para controlar cómo se traducen ciertos términos de interfaz o nombres que deben permanecer en inglés. Durante la traducción automática, estos marcadores se comparan con bases de datos de localización para asegurar que se respeta correctamente la terminología.

La guía de estilo de Adobe también recoge problemas específicos de compatibilidad: por ejemplo, el uso de guiones bajos en texto alternativo de imágenes puede causar errores de representación, por lo que recomiendan utilizar guiones normales en nombres de archivo y alt. Igualmente, desaconsejan el uso del símbolo & en títulos salvo que se codifique como &.

GitHub Flavored Markdown (GFM) y CommonMark

GitHub popularizó enormemente Markdown al extenderlo con funciones prácticas para el trabajo colaborativo: checklists, referencias a issues, sintaxis ampliada para tablas, manejo de resaltado de código con infinidad de lenguajes, etc. GFM se define como un superconjunto de CommonMark, que busca ser un estándar formal y consistente del lenguaje.

En GFM, los bloques de código delimitados por vallas permiten añadir una “cadena de información” tras el lenguaje, que muchas plataformas interpretan como clases adicionales. Esto hace posible, por ejemplo, marcar un bloque como ejemplo correcto o incorrecto, ocultarlo en la versión final o pedir que un analizador de código ignore ese bloque combinando el nombre del lenguaje con sufijos como -nolint.

Markdown personalizado en MDN Web Docs

MDN Web Docs, la gran referencia de documentación para tecnologías web, adopta GFM como base, pero impone ciertas normas particulares. Solo se permiten enlaces en línea, por motivos de claridad; se extiende la sintaxis para soportar notas, advertencias y observaciones a través de citas en bloque cuyo primer párrafo siga un patrón concreto; y se define una forma específica de escribir listas de definiciones reutilizando la estructura de listas no ordenadas anidadas.

Las notas de MDN, por ejemplo, se crean con una cita en bloque cuyo primer párrafo empiece con una palabra clave seguida de dos puntos, y el sistema las transforma en cuadros visuales destacados. Estas cadenas están localizadas, de modo que en cada idioma el marcador se escribe en la lengua correspondiente, pero la plataforma sigue siendo capaz de reconocerlas y tratarlas como notas o advertencias.

En cuanto al código, MDN especifica una lista cerrada de identificadores de lenguaje válidos para los bloques con vallas: JavaScript, TypeScript, CSS, HTML, Bash, JSON, YAML y muchos otros, además de un modo plain para texto plano. Si se necesita mostrar código inválido o con formato no estándar, puede añadirse el sufijo -nolint para que herramientas automáticas de formateo como Prettier lo ignoren.

MDN también hace recomendaciones SEO específicas para su contenido: el primer párrafo real del artículo actúa como resumen de la página y se usa para meta descripciones y listados de contenido. Por ello, piden que sea breve, claro y representativo del resto del texto.

Buenas prácticas y casos especiales al escribir en Markdown

Más allá de la pura sintaxis, la experiencia acumulada por proyectos como Adobe, MDN o grandes blogs técnicos deja claro que no todo vale a la hora de escribir en Markdown. Hay pequeños detalles que marcan la diferencia entre un documento limpio y uno problemático.

Por ejemplo, si copias texto desde un procesador de texto rico, es fácil que se cuelen apóstrofes y comillas “inteligentes”. Muchos procesadores de Markdown no las manejan bien y pueden acabar convertidas en caracteres raros tras la publicación. Lo recomendable es sustituirlas por comillas rectas o, si es imprescindible, codificarlas con sus entidades HTML.

Otro punto delicado son los caracteres con significado especial en HTML, como los signos menor y mayor que. Cuando no estás escribiendo código HTML sino texto normal, conviene escapar estos símbolos como &lt; y &gt; para evitar que el procesador los interprete como etiquetas. Lo mismo ocurre con la barra invertida en Markdown, que se usa para escapar caracteres de formato y debe aplicarse cuando quieres mostrar literalmente asteriscos, almohadillas o guiones bajos.

En los títulos, muchas guías de estilo desaconsejan introducir el símbolo & sin codificarlo, porque puede provocar comportamientos extraños en ciertas herramientas. Es preferible escribir “y” o usar la entidad &amp; si de verdad necesitas el símbolo de ampersand por cuestiones de marca.

Por último, cuando se mezcla HTML con Markdown, la recomendación general es clara: si necesitas algo que Markdown no cubre bien (tablas complejas, clases, atributos específicos…), puedes recurrir a HTML sin problema, pero procurando no mezclar sintaxis en el interior de una misma etiqueta. Es buena idea rodear los bloques HTML con líneas en blanco y evitar sangrías innecesarias para que el parser no se confunda.

Dominar Markdown con un poco de calma te permite escribir más rápido, cometer menos errores de formato y mantener tus textos limpios y reutilizables. Aunque existan distintas variantes y matices según la plataforma, la base es tan simple y legible que, una vez interiorizada, te resultará difícil volver a un editor WYSIWYG clásico para trabajos de escritura intensa.