Chuleta de Markdown: toda la sintaxis que necesitas, con ejemplos

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero creado por John Gruber en 2004. Su objetivo es sencillo: un texto fácil de leer tal cual y que se convierta limpiamente a HTML. Hoy es el estándar para archivos README, documentación, foros de desarrolladores, apps de notas como Obsidian, chats como Slack y Discord y muchas plataformas de blogs.

El dialecto más común es GitHub Flavored Markdown (GFM), que añade a la sintaxis original tablas, listas de tareas, tachado y enlaces automáticos.

Títulos

# Título 1
## Título 2
### Título 3
#### Título 4

Usa un solo título # por documento (el título principal) y respeta el orden de los niveles. Pon siempre un espacio después del #.

Énfasis

Markdown	Resultado
**negrita**	negrita
*cursiva* o _cursiva_	cursiva
***negrita cursiva***	negrita cursiva
~~tachado~~	tachado (GFM)
`código en línea`	código en línea

Enlaces e imágenes

[Texto del enlace](https://example.com)
[Enlace con título](https://example.com "Texto al pasar el ratón")
<https://example.com>

![Texto alternativo que describe la imagen](imagen.png)

[Enlace por referencia][docs]
[docs]: https://example.com/docs

Escribe un texto alternativo con sentido para las imágenes. Los lectores de pantalla lo leen en voz alta y ayuda a los buscadores a entender la imagen.

Listas

- Elemento con viñeta
- Otro elemento
  - Elemento anidado (sangría de 2 espacios)

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

- [x] Tarea terminada
- [ ] Tarea pendiente

Las listas de tareas (- [ ]) forman parte de GFM y se muestran como casillas en GitHub y en muchos editores.

Citas

> Esto es una cita.
>
> Puede ocupar varios párrafos.

Bloques de código

```js
function greet(name) {
  return `¡Hola, ${name}!`;
}
```

Rodea el código con tres comillas invertidas y añade el nombre del lenguaje (js, python, bash, json…) para que el resaltado de sintaxis pueda colorearlo.

Tablas

| Herramienta | Categoría | Precio |
| :---------- | :-------: | -----: |
| Resumidor   | Texto     | Gratis |
| OCR         | Imágenes  | Gratis |

Los dos puntos de la fila separadora fijan la alineación: :--- a la izquierda, :---: centrado, ---: a la derecha. No hace falta que las columnas estén alineadas en el código fuente; solo lo hace más fácil de leer.

Separadores y saltos de línea

Tres guiones solos en una línea crean un separador:

---

Termina una línea con dos espacios (o una barra invertida)\
para forzar un salto de línea dentro de un párrafo.

Una línea en blanco empieza un párrafo nuevo. La mayoría de los problemas de formato vienen de líneas en blanco que faltan entre párrafos, listas y títulos.

Escapar caracteres especiales

Para mostrar un símbolo que Markdown interpretaría, pon una barra invertida delante: \*sin cursiva\*, \#no es un título, \[no es un enlace\].

Pruébalo en directo y exporta a HTML

1. Abre el editor de Markdown a HTML gratuito.
2. Escribe Markdown o usa la barra de herramientas para títulos, negrita, enlaces, listas, tablas y código.
3. Mira cómo se actualiza la vista previa mientras escribes. Cambia a la pestaña HTML para ver el código generado.
4. Copia el HTML, descarga una página .html completa o guarda tu archivo .md.

Tu borrador se guarda automáticamente en tu navegador y no se sube nada.

Consejos de Markdown

• Deja líneas en blanco alrededor de títulos, listas, bloques de código y tablas.
• Sé coherente: elige - o * para las viñetas y no lo cambies.
• Usa enlaces relativos en los repositorios ([Instalación](docs/setup.md)) para que funcionen en todas las ramas.
• Previsualiza antes de publicar. Las plataformas varían un poco en las extensiones que admiten.
• Usa HTML cuando lo necesites. La mayoría de los procesadores de Markdown aceptan HTML en línea para lo que Markdown no puede hacer, como <kbd> o <details>, aunque algunas plataformas lo eliminan por seguridad.

Preguntas frecuentes

¿Qué diferencia hay entre Markdown y GitHub Flavored Markdown?

GFM es una ampliación del Markdown estándar (CommonMark) que añade tablas, listas de tareas, tachado y enlaces automáticos.

¿Cómo subrayo texto en Markdown?

Markdown no tiene sintaxis de subrayado, porque el texto subrayado parece un enlace. Si de verdad lo necesitas, usa HTML: <u>texto</u>.

¿Cómo añado un salto de línea sin crear un párrafo nuevo?

Termina la línea con dos espacios o una barra invertida, o usa <br>.

¿Es seguro usar el HTML exportado en mi web?

Sí. El HTML exportado es un marcado limpio y semántico sin estilos en línea, y la vista previa se sanea para bloquear scripts.

En resumen

Una docena de símbolos cubre casi todo lo que vas a escribir en Markdown. Ten esta chuleta a mano, deja líneas en blanco entre bloques y previsualiza el texto antes de publicarlo.