Markdown es un lenguaje de marcado ligero: escribes texto plano con unos pocos símbolos y se convierte en HTML con formato. Es lo que usan los README.md de GitHub, la documentación de muchos proyectos, Notion, Obsidian, Discord o Reddit.
Esta guía empieza con una chuleta para consultar rápido y después explica cada elemento con un ejemplo.
Chuleta de Markdown
| Elemento | Sintaxis |
|---|---|
| Encabezado | # H1, ## H2, ### H3 |
| Negrita | **texto** |
| Cursiva | *texto* |
| Negrita y cursiva | ***texto*** |
| Tachado | ~~texto~~ |
| Cita | > texto |
| Lista | - elemento |
| Lista numerada | 1. elemento |
| Lista de tareas | - [ ] tarea |
| Enlace | [texto](https://url.com) |
| Imagen |  |
| Código en línea | `código` |
| Bloque de código | ``` en una línea antes y otra después |
| Línea horizontal | --- |
Cómo escribir un encabezado en Markdown
Usa almohadillas (#) al principio de la línea. El número de almohadillas indica el nivel, de # (el más grande) a ###### (el más pequeño). Deja un espacio entre las almohadillas y el texto.
# Encabezado de nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
#### Encabezado de nivel 4
Usa un solo # por documento, para el título principal, y organiza el resto con ## y ###.
Párrafos y saltos de línea
Para crear un párrafo nuevo, deja una línea en blanco entre los dos bloques de texto.
Si solo pulsas Intro, Markdown une las dos líneas en el mismo párrafo. Para forzar un salto de línea sin empezar otro párrafo, termina la línea con dos espacios o con una barra invertida (\):
Primera línea\
Segunda línea, en el mismo párrafo
Cómo escribir en negrita y cursiva en Markdown
- Negrita: dos asteriscos (
**) o dos guiones bajos (__) a cada lado. - Cursiva: un asterisco (
*) o un guion bajo (_) a cada lado. - Negrita y cursiva: tres asteriscos (
***) a cada lado.
**Negrita** o __Negrita__
*Cursiva* o _Cursiva_
***Negrita y cursiva***
Resultado: Negrita, Cursiva y Negrita y cursiva.
Para marcar solo una parte de una palabra, usa asteriscos: super**importante** funciona, mientras que con guiones bajos muchos editores no lo aplican.
Cómo tachar texto en Markdown
Pon dos virgulillas (~~) al principio y al final del texto.
~~Texto tachado~~
Resultado: Texto tachado
Cómo escribir una cita en Markdown
Empieza la línea con el símbolo mayor que (>). Para una cita dentro de otra, usa >>.
> Esta es una cita
>
>> Y esta es una cita anidada
Esta es una cita
Y esta es una cita anidada
Cómo hacer una lista en Markdown
Lista con viñetas
Empieza cada línea con un guion (-), un asterisco (*) o un signo más (+) seguido de un espacio. Intenta usar siempre el mismo símbolo.
- Manzanas
- Peras
- Naranjas
- Manzanas
- Peras
- Naranjas
Lista numerada
Escribe un número seguido de un punto. Los números no tienen que ser correlativos: Markdown numera la lista por ti, así que puedes escribir 1. en todas las líneas.
1. Clona el repositorio
2. Instala las dependencias
3. Arranca el proyecto
- Clona el repositorio
- Instala las dependencias
- Arranca el proyecto
Listas anidadas
Para meter una lista dentro de otra, indenta los elementos con dos o cuatro espacios.
- Frontend
- React
- Vue
- Backend
- Node.js
- Frontend
- React
- Vue
- Backend
- Node.js
Lista de tareas
Añade [ ] para una tarea pendiente y [x] para una completada. Funciona en GitHub, GitLab y la mayoría de editores.
- [x] Escribir el README
- [ ] Añadir capturas de pantalla
- [ ] Publicar la primera versión
- Escribir el README
- Añadir capturas de pantalla
- Publicar la primera versión
Cómo poner un enlace en Markdown
Escribe el texto del enlace entre corchetes y la URL entre paréntesis, sin espacio entre ellos. Opcionalmente, añade un título entre comillas que aparece al pasar el ratón.
[Mi web](https://girgetto.it)
[Mi web](https://girgetto.it "Página de inicio")
<https://girgetto.it>
Resultado: Mi web
Para enlazar a una sección del mismo documento, usa el nombre del encabezado en minúsculas y con guiones: [Ir a tablas](#cómo-hacer-una-tabla-en-markdown).
Cómo poner una imagen en Markdown
Es igual que un enlace, pero con un signo de exclamación (!) delante. El texto entre corchetes es el texto alternativo: descríbelo bien, porque lo leen los lectores de pantalla y los buscadores.
Para que la imagen sea también un enlace, mete la imagen dentro de un enlace:
[](https://ejemplo.com)
Markdown no permite cambiar el tamaño de una imagen. Si lo necesitas, usa HTML: <img src="logo.png" alt="Logo" width="200">.
Cómo escribir código en Markdown
Código en línea
Rodea el código con comillas invertidas (`, el acento grave).
Ejecuta `npm install` para instalar las dependencias.
Resultado: Ejecuta npm install para instalar las dependencias.
Bloque de código
Escribe tres comillas invertidas en una línea antes del código y otras tres después. Si añades el nombre del lenguaje justo después de las primeras, el código se muestra con resaltado de sintaxis.
```javascript
const suma = (a, b) => a + b;
console.log(suma(5, 5));
```
const suma = (a, b) => a + b;
console.log(suma(5, 5));
Algunos lenguajes habituales: javascript, typescript, python, bash, json, html, css, diff.
Cómo hacer una tabla en Markdown
Separa las columnas con barras verticales (|) y pon una fila de guiones (---) debajo de la cabecera. Con los dos puntos (:) en esa fila eliges la alineación de cada columna.
| Comando | Descripción | Obligatorio |
| :------------ | :---------------------: | ----------: |
| `npm install` | Instala dependencias | Sí |
| `npm test` | Ejecuta los tests | No |
| Comando | Descripción | Obligatorio |
|---|---|---|
npm install |
Instala dependencias | Sí |
npm test |
Ejecuta los tests | No |
:---alinea a la izquierda:---:centra---:alinea a la derecha
No hace falta que las columnas estén alineadas en el texto: basta con que cada fila tenga el mismo número de barras.
Cómo poner una línea horizontal en Markdown
Escribe tres guiones (---), asteriscos (***) o guiones bajos (___) en una línea sola. Deja una línea en blanco antes, porque --- justo debajo de un texto lo convierte en un encabezado.
Texto de arriba
---
Texto de abajo
Cómo escapar caracteres en Markdown
Si quieres mostrar un símbolo que Markdown interpreta, como un asterisco, ponle delante una barra invertida (\).
\*Esto no sale en cursiva\*
Resultado: *Esto no sale en cursiva*
Se pueden escapar estos caracteres: \ ` * _ {} [] () # + - . ! |
Cómo crear una sección desplegable en Markdown
Markdown acepta HTML, así que puedes usar las etiquetas <details> y <summary> para crear un bloque que se abre al hacer clic. Es útil para ocultar logs largos o instrucciones opcionales en un README. Deja una línea en blanco después de </summary> para que el Markdown de dentro se procese.
<details>
<summary>Ver instrucciones de instalación</summary>
1. Clona el repositorio
2. Ejecuta `npm install`
</details>
Ver instrucciones de instalación
- Clona el repositorio
- Ejecuta
npm install
Dónde funciona cada cosa
Los elementos básicos (encabezados, negrita, cursiva, listas, enlaces, imágenes, citas y código) funcionan en cualquier sitio. Las tablas, el tachado y las listas de tareas son extensiones de GitHub Flavored Markdown (GFM): funcionan en GitHub, GitLab, VS Code y la mayoría de editores modernos, pero algunas herramientas antiguas no los muestran.