Markdown: Referencia Completa de Sintaxis para Escritores y Desarrolladores

Markdown está en todas partes. Es el formato de escritura predeterminado en GitHub, la columna vertebral de la mayoría de los generadores de sitios estáticos, el lenguaje nativo de herramientas como Obsidian y Notion, y el formato al que recurren los desarrolladores para escribir READMEs, documentación y notas técnicas. A pesar de ser ubicuo, muchos escritores y desarrolladores solo aprenden lo básico — negrita, cursiva y algunos niveles de encabezado — y se pierden las características que hacen a Markdown genuinamente potente para la escritura estructurada.

Puedes escribir y previsualizar Markdown al instante con el Editor Markdown de BrowseryTools — gratuito, sin registro, todo se ejecuta en tu navegador.

Quién creó Markdown y por qué

Markdown fue creado por John Gruber, en colaboración con Aaron Swartz, y publicado en 2004. El objetivo declarado de Gruber era crear un formato de escritura en texto plano que sea legible tal cual — antes de cualquier renderizado — y que se convierta limpiamente a HTML válido. El nombre es un juego de palabras con "markup language" (lenguaje de marcado — HTML es HyperText Markup Language), invirtiendo el concepto: en lugar de añadir sintaxis para controlar el formato, Markdown usa los hábitos de puntuación natural que la gente ya había desarrollado en el correo electrónico en texto plano.

La motivación era práctica. HTML es verboso y distrae al escribirlo en línea. Una oración como <p>Esto es un texto <strong>importante</strong>.</p> requiere una carga mental significativa comparada con Esto es un texto **importante**. Gruber quería que los blogueros y escritores se centraran en las palabras, no en las etiquetas. La especificación original de Markdown era un script Perl que convertía archivos Markdown en texto plano a HTML.

Sintaxis básica

La sintaxis principal de Markdown cubre todo lo que la mayoría de los escritores necesitan para documentos estructurados.

Encabezados

Usa almohadillas para crear encabezados. Una almohadilla para H1, dos para H2, hasta seis para H6. La mayoría de las guías de estilo recomiendan un solo H1 por documento (típicamente el título) y usar H2–H4 para la jerarquía del contenido.

# Encabezado 1
## Encabezado 2
### Encabezado 3
#### Encabezado 4

Énfasis y negrita

*cursiva* o _cursiva_
**negrita** o __negrita__
***negrita y cursiva***
~~tachado~~

Enlaces e imágenes

[Texto del enlace](https://example.com)
[Enlace con título](https://example.com "Título de la página")
![Texto alternativo](image.png)
![Texto alternativo](image.png "Título de la imagen")

Listas

Las listas desordenadas usan guiones, asteriscos o signos más. Las listas ordenadas usan números seguidos de puntos. Los elementos sangrados (2 o 4 espacios) crean listas anidadas.

- Elemento desordenado
- Otro elemento
  - Elemento anidado

1. Primero
2. Segundo
3. Tercero

Código

El código en línea usa tildes graves simples. Los bloques de código delimitados usan tres tildes graves con un identificador de lenguaje opcional para el resaltado de sintaxis.

Usa `console.log()` para depurar.

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Citas en bloque

> Esto es una cita en bloque.
> Puede abarcar varias líneas.
>
> > Las citas en bloque anidadas también funcionan.

Reglas horizontales

Tres o más guiones, asteriscos o subrayados solos en una línea crean una regla horizontal.--- es la convención más habitual.

Sintaxis extendida

La especificación original de Markdown omitió varias características que los escritores necesitan habitualmente. La sintaxis extendida, compatible con la mayoría de los procesadores modernos, añade estas capacidades.

Tablas

| Columna 1 | Columna 2 | Columna 3 |
|-----------|:---------:|----------:|
| Izquierda | Centro    | Derecha   |
| alineada  | alineado  | alineada  |

La posición de los dos puntos en la fila separadora controla la alineación: izquierda (predeterminada), centro (dos puntos en ambos lados) o derecha (dos puntos a la derecha).

Listas de tareas

- [x] Escribir el primer borrador
- [x] Revisión por pares
- [ ] Ediciones finales
- [ ] Publicar

Notas al pie

Aquí hay una afirmación que necesita una cita.[^1]

[^1]: La fuente de apoyo o explicación va aquí.

Variantes de Markdown: CommonMark, GFM y MDX

La especificación original de Markdown tenía ambigüedades — lugares donde los procesadores tomaban decisiones diferentes sobre casos extremos. Esto llevó a implementaciones incompatibles entre diferentes herramientas. Varios esfuerzos de estandarización surgieron para resolverlo.

• CommonMark — una especificación rigurosa que resuelve cada ambigüedad en la especificación original de Markdown con una suite de pruebas formal. Adoptada por Discourse, Reddit, Stack Overflow y muchos otros. La variante más interoperable.
• GitHub Flavored Markdown (GFM) — la extensión de CommonMark de GitHub que añade tablas, listas de tareas, tachado, autoenlaces y URLs literales. Si escribes archivos README o comentarios en GitHub, estás usando GFM.
• MDX — Markdown extendido con soporte de componentes JSX, usado ampliamente en sitios de documentación basados en React (docs de Next.js, Docusaurus, Astro). Permite importar e incrustar componentes React directamente en archivos Markdown.
• MultiMarkdown / Pandoc Markdown — extensiones con muchas funciones para escritura académica, con soporte para citas, ecuaciones matemáticas (LaTeX) y formatos de tabla complejos.

Dónde se usa Markdown

• GitHub y GitLab — los archivos README, issues, pull requests, wikis y comentarios se renderizan con Markdown
• Notion — admite importación/exportación de Markdown y un subconjunto de atajos de Markdown para el formato en línea
• Obsidian — una aplicación de gestión del conocimiento construida completamente sobre archivos Markdown con extensiones de wikienlaces
• Generadores de sitios estáticos — Jekyll, Hugo, Gatsby, Astro y Next.js usan todos Markdown o MDX como formato de contenido predeterminado
• Plataformas de documentación — ReadTheDocs, GitBook y Docusaurus están construidos alrededor de Markdown
• Plataformas de chat — Slack, Discord y Teams admiten subconjuntos de Markdown para el formato de mensajes
• Clientes de correo electrónico — algunos clientes (Superhuman, HEY) admiten la entrada en Markdown

Markdown frente a editores de texto enriquecido

Los editores de texto enriquecido (WYSIWYG — What You See Is What You Get / Lo que ves es lo que obtienes) como Google Docs, Microsoft Word o el editor integrado de Contentful muestran el resultado formateado mientras escribes. Markdown muestra el código fuente sin procesar. Los compromisos son reales.

• Ventajas de Markdown — archivos de texto plano, funciona en cualquier editor, controlable con git, sin dependencia de proveedores, flujo de trabajo rápido solo con teclado
• Ventajas del texto enriquecido — inmediatamente visual, sin sintaxis que aprender, más fácil para colaboradores no técnicos, mejor para formatos complejos (notas al pie, comentarios, control de cambios)

Para escritura técnica, documentación de desarrolladores y gestión personal del conocimiento, la portabilidad y la compatibilidad con el control de versiones de Markdown lo convierten en la mejor opción. Para documentos empresariales colaborativos o contenido con requisitos de formato complejos, un editor de texto enriquecido suele ser más práctico.

Errores habituales en Markdown

• Líneas en blanco faltantes — la mayoría de los elementos de bloque (encabezados, listas, bloques de código) requieren una línea en blanco antes y después para renderizarse correctamente
• Espacios después de las almohadillas — ##Encabezado sin espacio después de las almohadillas no es un encabezado en la mayoría de los procesadores
• Marcadores de lista inconsistentes — mezclar - y * en la misma lista puede producir resultados inesperados en algunos procesadores
• Olvidar escapar caracteres especiales — los asteriscos, subrayados y tildes graves dentro del texto necesitan un escape de barra invertida si deben renderizarse literalmente
• Asumir que la sintaxis extendida es universal — las tablas y las listas de tareas son características de GFM no compatibles con todos los procesadores; comprueba tu entorno objetivo

El Editor Markdown de BrowseryTools proporciona una vista previa en vivo para que puedas detectar problemas de renderizado inmediatamente mientras escribes, sin necesidad de copiar el texto en otra herramienta. Pega tu Markdown y ve el resultado HTML renderizado en paralelo.