Markdown: guía completa del lenguaje de formato ligero

Inicio » Windows » Markdown: guía completa del lenguaje de formato ligero

Markdown se ha convertido en el estándar de facto para escribir texto con formato sin necesidad de pelearte con el HTML. Es ligero, fácil de leer incluso en bruto y se adapta tanto a documentación técnica como a blogs, notas personales o correos electrónicos largos.

A lo largo de este artículo vas a encontrar una guía muy completa del lenguaje de marcado Markdown: desde la sintaxis básica (encabezados, negritas, listas…) hasta las extensiones más avanzadas usadas por plataformas como GitHub, Adobe, MDN, o motores como CommonMark y GFM. Verás también buenas prácticas, pequeños trucos y en qué casos conviene recurrir a HTML directamente.

Qué es Markdown y por qué se usa tanto

Markdown es un lenguaje de marcado ligero creado en 2004 por John Gruber, con la idea de permitir escribir texto plano que se pueda convertir de forma automática a HTML válido, sin perder legibilidad humana. Es decir, el fichero sin procesar ya se puede leer cómodamente, cosa que no ocurre con HTML o XML llenos de etiquetas.

La sintaxis se basa en caracteres muy intuitivos como almohadillas, asteriscos, guiones o corchetes. Eso permite que puedas escribir en cualquier editor de texto, sin plug‑ins raros ni IDEs pesados. Luego, una herramienta (un conversor, un CMS, GitHub, etc.) se encarga de transformar ese archivo Markdown en HTML u otros formatos como PDF.

Desde su creación, han ido apareciendo extensiones y variantes de Markdown para cubrir nuevas necesidades: Markdown Extra, GitHub Flavored Markdown (GFM), CommonMark (que busca estandarizar el lenguaje) o variantes específicas como el Markdown ampliado de Adobe o el usado en MDN Web Docs.

Hoy en día Markdown es omnipresente en documentación técnica, proyectos open source, blogs estáticos (Jekyll, Hugo, Astro…), notas personales (Obsidian, Notion) o incluso presentaciones generadas con herramientas como Pandoc. Básicamente, te sirve para casi cualquier texto estructurado que termine en web o PDF.

Conceptos básicos de Markdown

La base de Markdown es muy sencilla: un párrafo es simplemente una o más líneas de texto separadas por una línea en blanco. No hay que envolverlo con etiquetas especiales, el procesador ya lo convertirá a <p> cuando toque.

Si quieres escribir un encabezado, un listado o cualquier otro elemento, lo único que haces es añadir un carácter específico al principio o alrededor del texto. Esa es toda la “magia”. A partir de aquí, vamos pieza por pieza.

Encabezados en Markdown

Los encabezados se definen con el símbolo de almohadilla. El número de almohadillas indica el nivel de encabezado, de forma equivalente a h1, h2, h3, etc. en HTML.

• Encabezado de nivel 1: # Título de nivel 1 → <h1>
• Encabezado de nivel 2: ## Título de nivel 2 → <h2>
• Encabezado de nivel 3: ### Título de nivel 3 → <h3>
• Y así hasta seis niveles (<h1> a <h6>)

Es una buena práctica dejar siempre un espacio entre el grupo de almohadillas y el texto del encabezado para asegurar compatibilidad con todos los procesadores. Algunas plataformas limitan el nivel máximo (por ejemplo, cuatro niveles en ciertos sistemas de ayuda), y otras permiten hasta seis como en HTML estándar.

Existe también una alternativa “clásica” donde un encabezado de nivel 1 se marca subrayándolo con signos igual (=) y uno de nivel 2 con guiones (-), en una línea separada. Aunque está soportado en muchas herramientas, la sintaxis de almohadillas es la más habitual hoy.

Formato de texto: negrita, cursiva y combinaciones

Para resaltar texto, Markdown se basa sobre todo en asteriscos y guiones bajos. Lo importante es abrir y cerrar el texto resaltado con el mismo número de símbolos y sin espacios innecesarios.

Negrita

Para marcar texto en negrita, se encierran las palabras entre dos asteriscos o dos guiones bajos a cada lado. Ejemplos típicos:

• texto en negrita
• __texto en negrita__

Incluso puedes resaltar parte de una palabra, colocándolos sin espacios en medio del término. Aunque también se puede hacer con guiones bajos, no hay un estándar totalmente claro para casos complejos, de modo que lo más recomendable es usar siempre asteriscos para evitar sorpresas en ciertas herramientas.

Cursiva

La cursiva se marca con un solo asterisco o un solo guion bajo al principio y al final del texto que quieras enfatizar:

• *texto en cursiva*
• _texto en cursiva_

Al igual que con la negrita, puedes aplicar este formato a letras concretas dentro de una palabra, siempre que no haya espacios entre los símbolos y esas letras. Varios procesadores se lían cuando se usan guiones bajos en medio de palabras, así que aquí también es más seguro apostar por el asterisco.

Negrita y cursiva a la vez

Si quieres combinar ambos efectos, usa tres asteriscos o tres guiones bajos alrededor del texto que quieres destacar:

• *muy importante*
• ___muy importante___

También se permiten combinaciones mixtas como __*texto*__ o _texto_, donde se mezclan asteriscos y guiones bajos, aunque la compatibilidad con tres guiones bajos en mitad de una palabra es irregular. Por coherencia, de nuevo, mejor asteriscos si quieres que tu documento funcione en el mayor número posible de plataformas.

Párrafos, saltos de línea y reglas horizontales

En Markdown, un párrafo se crea dejando una línea en blanco entre bloques de texto. No hace falta nada más: el procesador añadirá las etiquetas HTML de párrafo cuando convierta el documento.

Si en lugar de un nuevo párrafo quieres forzar un salto de línea simple dentro del mismo párrafo, hay varias opciones según la especificación y el procesador:

• Usar dos o más espacios al final de la línea antes de pulsar Intro.
• Incluir explícitamente la etiqueta HTML <br>.
• En algunas implementaciones, basta con pulsar Intro una vez, aunque no es comportamiento oficial en todas.
• Algunas variantes (como CommonMark) permiten usar una barra invertida \ al final de la línea.

Para insertar una línea horizontal que separe secciones tienes tres formas principales: tres o más asteriscos (***), tres o más guiones (---) o tres o más guiones bajos (___). Deben ir solos en una línea, sin texto ni espacios a los lados, y suele recomendarse dejar una línea en blanco antes y después para mayor compatibilidad.

Listas: numeradas, con viñetas y anidadas

Las listas son uno de los elementos más usados en Markdown. Puedes crear listas ordenadas (numeradas) y desordenadas (con viñetas), e incluso mezclarlas y anidarlas varias capas hacia dentro.

Listas numeradas

Para hacer una lista ordenada, se coloca un número seguido de un punto y un espacio delante de cada elemento:

• 1. Primer paso
• 2. Segundo paso
• 3. Tercer paso

La curiosidad es que no hace falta que los números estén en orden ni que cambien: muchas implementaciones (como GitHub) renumeran automáticamente empezando siempre por 1 al renderizar. Basta con que el primer elemento empiece en 1. Algunas variantes aceptan también números seguidos de paréntesis en lugar de punto, pero no todas, por lo que no es lo más recomendable si buscas compatibilidad.

Listas con viñetas

Las listas no ordenadas se crean poniendo un guion, un asterisco o un signo más seguido de un espacio antes de cada ítem:

• - Elemento
• * Elemento
• + Elemento

En teoría puedes mezclar símbolos en la misma lista, aunque muchas guías recomiendan usar siempre el mismo delimitador para mantener la lectura y evitar problemas con ciertas herramientas que son más estrictas.

Listas anidadas y contenido dentro de listas

Las listas pueden contener otras listas, párrafos, imágenes, citas o bloques de código. Para anidar una lista dentro de otra, se añade una sangría, normalmente de cuatro espacios o una tabulación, antes de los elementos internos.

Si quieres incluir un párrafo, una imagen o una cita dentro de un elemento de lista, lo habitual es:

• Dejar una línea en blanco tras la línea de lista.
• Añadir cuatro espacios (o más) delante del contenido que quieras anidar.

En el caso de bloques de código dentro de listas, a menudo se necesitan 8 espacios o dos tabulaciones para que se rendericen bien, aunque la sintaxis de bloques con triple comilla invertida simplifica mucho este problema.

Citas en bloque y citas anidadas

Las citas en bloque se inician con el carácter mayor que al principio de la línea. Cada línea citada comienza con > y, en la mayoría de implementaciones, se recomienda que haya una línea en blanco antes y después del bloque de cita.

Puedes crear citas de varios párrafos repitiendo el patrón y usando una línea que contenga solo > para marcar el salto entre párrafos dentro de la misma cita. Además, es posible anidar citas añadiendo más de un símbolo > por línea, lo que da lugar a distintos niveles de profundidad.

Dentro de una cita se pueden incluir muchos otros elementos Markdown: encabezados, listas, enlaces, bloques de código, etc.. Algunas plataformas como MDN usan las citas, combinadas con texto en negrita al inicio, para construir cajas de nota, advertencia u observación. Por ejemplo, una cita cuyo primer párrafo comience por Nota: puede transformarse en una caja resaltada “Nota”.

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

Markdown diferencia entre código en línea (dentro de un párrafo) y bloques de código de varias líneas. Ambos son fundamentales en documentación técnica.

Código en línea

Para marcar una porción de código dentro de una frase, se rodea con comillas invertidas (backticks):

• Este es un ejemplo de `código en línea` dentro de una frase.

Si el propio código contiene comillas invertidas, hay que duplicar el número de backticks externos y dejar un espacio entre las internas y las externas cuando el código empiece o termine con ese carácter. Así evitas errores de interpretación al procesar el documento.

Bloques de código

Para bloques de varias líneas hay dos enfoques principales:

• Sangrar las líneas con cuatro espacios o una tabulación. Cualquier conjunto de líneas consecutivas con esa sangría se convierte en un bloque de código preformateado.
• Usar tres comillas invertidas consecutivas (vallas o “fences”) antes y después del bloque. Esta forma permite además indicar el lenguaje de programación justo después de las comillas de apertura, por ejemplo ```javascript, para que el procesador haga resaltado de sintaxis.

Muchas plataformas (como GitHub, Adobe Docs o MDN) utilizan estas vallas de código con una “cadena de información” que indica tanto el lenguaje como clases adicionales. Por ejemplo, en MDN se admiten identificadores como js, ts, css, html, bash, json, etc., y sufijos como -nolint para evitar que el bloque pase por linters o formateadores automáticos.

Además, ciertas cadenas de información como example-good o example-bad sirven para marcar ejemplos “buenos” o “malos”, y hidden permite ocultar el bloque en la página, manteniéndolo sólo para ejemplos en vivo u otros usos internos.

Enlaces, imágenes y variantes especiales

Los vínculos son uno de los pilares de Markdown. La sintaxis general para un enlace en línea es:

• [texto del enlace](https://ejemplo.com)

Entre corchetes va el texto que se mostrará, y entre paréntesis la URL. Es importante que no haya espacios entre el corchete de cierre y el paréntesis de apertura. Opcionalmente, puedes añadir un título entre comillas detrás de la URL: [texto](https://ejemplo.com "Título del enlace").

Algunas variantes permiten crear enlaces automáticos a URL usando solo el enlace sin texto, o emplear mailto: para direcciones de correo. También se pueden enlazar anclas dentro de la misma página usando almohadillas, por ejemplo: [Ir a sección](#id-de-la-seccion).

Enlaces de referencia

Los enlaces de referencia separan el texto visible del destino real, lo que mejora la legibilidad cuando las URLs son largas. Funcionan en dos partes:

• Un enlace con referencia: [Texto descriptivo][id] o [Texto descriptivo] [id].
• En cualquier parte del documento, una definición de referencia: [id]: https://ejemplo.com "Título opcional".

El procesador unirá ambos elementos para crear el enlace final. Es habitual colocar las referencias al final del documento o de la sección para tenerlas todas juntas.

Formato del texto de enlace

El texto de un enlace puede llevar formato adicional: negrita, cursiva o incluso código en línea. Por ejemplo, [documentación oficial](https://ejemplo.com) o [`funcion()`](https://ejemplo.com). Esto se respeta al renderizar el HTML.

Imágenes y enlaces con imagen

La sintaxis básica de una imagen se parece a la de un enlace, pero empezando con un signo de exclamación:

• ![Texto alternativo](https://servidor.com/imagen.png)

El texto entre corchetes se convertirá en el atributo alt de la imagen en HTML. También puedes añadir un título entre comillas tras la URL, que se traducirá al atributo title. Si quieres que la imagen sea clicable, simplemente envuelves la imagen con la sintaxis de enlace:

• [![alt](https://servidor.com/imagen.png)](https://destino.com)

En ciertos contextos (como firmas de correo o artículos específicos), algunas plataformas limitan el uso de imágenes o enlaces, así que conviene revisar siempre la documentación de la herramienta donde vayas a publicar.

Tablas en Markdown y cuándo usar HTML

Las tablas no forman parte del núcleo original de Markdown, pero muchas variantes (como Markdown Extra, GFM o el Markdown de Adobe y MDN) las soportan. La estructura básica se define con barras verticales para separar columnas y una fila de guiones para indicar el encabezado.

A nivel de estilo, en sitios como MDN se recomienda:

• Incluir tuberías iniciales y finales en cada fila (no omitirlas).
• Usar espacios para que las columnas queden alineadas de forma legible.
• Dejar una línea en blanco antes de la tabla para asegurar un renderizado correcto.

Sin embargo, las tablas de Markdown tienen limitaciones claras: no admiten fácilmente múltiples párrafos, listas o bloques complejos dentro de una celda, no permiten atributos como colspan o rowspan, y no se les pueden asignar clases salvo que recurras a HTML.

Por eso, cuando necesitas tablas más avanzadas, muy anchas (más de unos 150 caracteres de ancho en texto plano) o con características especiales (como las tablas de propiedades de MDN, con una columna de encabezado y otra de valores), lo más sensato es escribir directamente la tabla en HTML y, si hace falta, agregar una clase como properties para aplicar estilos específicos.

Extensiones y usos avanzados de Markdown

Muchas plataformas han desarrollado extensiones personalizadas sobre Markdown para cubrir necesidades de documentación, notas especiales, vídeos incrustados o elementos interactivos.

En el ecosistema de Adobe, por ejemplo, se habla de Adobe Markdown ampliado, que añade elementos para notas, consejos, bloques de código con propiedades extra y vídeos. Se aprovecha la sintaxis de citas (>) para invocar componentes avanzados (como notarías, advertencias visuales, etc.), y se permite añadir parámetros entre llaves tras ciertos elementos para modificar sus propiedades.

MDN Web Docs, por su parte, parte de GitHub Flavored Markdown (GFM) y añade reglas propias: solo se permiten enlaces en línea (prohibiendo los de referencia), se definen listas de definición usando listas no ordenadas de una forma especial, se introducen notas y advertencias detectadas por su texto inicial (traducciones de “Note:” o “Warning:”), y se define qué lenguajes pueden usarse en bloques de código con resaltado.

En estos entornos es frecuente que se combinen linters y formateadores como Prettier que reordenan tablas, corrigen sangrías y aplican un estilo homogéneo. Para bloquear el formateo de determinados bloques de código (por ejemplo, si el código está mal a propósito), se recurre al sufijo -nolint en la cadena de información de la valla de código.

Markdown y HTML: combinación y límites

Una de las grandes ventajas de Markdown es que permite incrustar HTML directamente en el documento en la mayoría de procesadores. Es habitual usar HTML para cambiar el color de un texto, ajustar atributos avanzados de una imagen, crear tablas complejas o manejar subíndices y superíndices.

Cuando se inserta HTML en varias líneas, es recomendable dejar una línea en blanco antes y después del bloque, y no aplicar sangrías raras al inicio de las etiquetas, para evitar que el analizador lo interprete como código o parte de una lista. Eso sí, normalmente no se puede usar sintaxis Markdown dentro de las etiquetas HTML (el texto interno se trata tal cual HTML).

En ciertas plataformas también hay restricciones: por ejemplo, en MDN se permite el uso de <sup> y <sub> solo cuando no queda más remedio; en títulos no se permite el símbolo & sin codificar (hay que usar & o sustituirlo por “y”); y las macros propias del sistema (como las de KumaScript) se insertan con su propia sintaxis específica.

Carácteres especiales y escape de símbolos

Los mismos símbolos que dan formato en Markdown (asteriscos, guiones bajos, almohadillas, corchetes…) son caracteres especiales que el procesador interpreta. Si quieres mostrarlos tal cual en pantalla, hay que “escaparlos” anteponiendo una barra invertida \.

Esto se aplica a la mayoría de elementos de formato. Por ejemplo, \* mostrará un asterisco literal, y \# evitará que una almohadilla al inicio de línea genere un encabezado. Hay que tener cuidado especial con las comillas invertidas dentro de código en línea: para representarlas sin romper la sintaxis, se duplican como se comentaba antes.

En el caso de las tablas extendidas, el carácter de tubería | se puede escapar con su equivalente HTML | si se quiere mostrar dentro de una celda sin romper la estructura de columnas.

También conviene prestar atención a apóstrofos y comillas “inteligentes” que puedan colarse al copiar texto desde procesadores de texto avanzados: si no se sustituyen por versiones simples o se codifican correctamente, es fácil que aparezcan caracteres extraños tipo It’s al publicarse.

Buenas prácticas, variantes y casos de uso

En la práctica, Markdown se ha extendido tanto que conviene acostumbrarse a convivir con varias variantes (CommonMark, GFM, Markdown Extra, implementaciones de CMS, etc.). La recomendación general es ceñirse a la sintaxis más estándar posible cuando quieras asegurar compatibilidad, y revisar la guía oficial de la plataforma en la que estás escribiendo cuando quieras usar extensiones avanzadas.

Entre las buenas prácticas más repetidas están:

• Evitar mezclar demasiadas variantes de una misma cosa (por ejemplo, varios estilos de listas) en el mismo documento.
• Usar asteriscos en vez de guiones bajos para formato de texto cuando hay dudas.
• Limitar el uso de tablas de Markdown a casos sencillos y recurrir a HTML para las complejas.
• Ser consistente con el estilo de encabezados y dejar claros los niveles jerárquicos.
• Guardar a mano referencias oficiales de sintaxis (como la de John Gruber, CommonMark o guías en español) mientras te acostumbras.

Quienes escriben a menudo para la web, documentación técnica o blogs suelen notar que, una vez interiorizada la sintaxis, se escribe más rápido y con menos errores que usando HTML directamente: se reduce el riesgo de olvidar etiquetas de cierre y se mantiene el flujo de escritura en texto plano, algo que se agradece especialmente en editores minimalistas o cuando se redacta desde móvil.

Al final, la gracia de Markdown es que te permite centrarte en el contenido mientras aplicas el formato justo con unos pocos caracteres fáciles de recordar. Conocer bien estas reglas básicas, las extensiones más comunes y las peculiaridades de cada plataforma hace que sea una herramienta tremendamente flexible para casi cualquier tipo de texto digital.