Sintaxis de Markdown: guía rápida con ejemplos
Actualizado
Markdown es una forma de dar formato a texto plano con símbolos sencillos: # para títulos, ** para negritas, - para listas. Lo usan GitHub, los archivos README, la documentación técnica y muchas apps de notas. Esta guía rápida reúne toda la sintaxis de Markdown en una página, con ejemplos listos para copiar y su resultado renderizado, incluidas las extensiones de GitHub (GFM) y los diagramas mermaid.
También disponible en: English · Русский · Tiếng Việt · Português (Brasil)
Sintaxis de Markdown de un vistazo
| Elemento | Sintaxis | Nota |
|---|---|---|
| Encabezado | # H1 ## H2 ### H3 | Hasta seis #; deja un espacio después. |
| Negrita | **texto en negrita** | |
| Cursiva | *cursiva* o _cursiva_ | |
| Negrita y cursiva | ***ambas*** | |
| Tachado | ~~eliminado~~ | GitHub Flavored Markdown (GFM). |
| Código en línea | `código` | |
| Bloque de código | ```js código ``` | La palabra después de las comillas invertidas define el lenguaje del resaltado. |
| Enlace | [texto](https://example.com) | |
| Imagen |  | |
| Lista con viñetas | - elemento | * y + también funcionan. |
| Lista numerada | 1. elemento | |
| Lista de tareas | - [ ] pendiente - [x] hecho | GFM. |
| Cita | > texto citado | |
| Tabla | | A | B | | --- | --- | | 1 | 2 | | GFM. Los dos puntos en la segunda fila definen la alineación. |
| Línea horizontal | --- | |
| Salto de línea | línea uno\ línea dos | Una barra invertida o dos espacios al final de la línea. |
| Nota al pie | Texto[^1] [^1]: La nota. | GFM. |
| Escapar un carácter | \*no es cursiva\* | Una barra invertida antes de cualquier símbolo de markdown. |
| Diagrama | ```mermaid flowchart LR A --> B ``` | Se renderiza en GitHub, GitLab y Docs MD. |
Referencia completa con ejemplos
Encabezados
Seis niveles
# H1 — título de la página
## H2 — sección
### H3 — subsección
#### H4
##### H5
###### H6H1 — título de la página
H2 — sección
H3 — subsección
H4
H5
H6
Lo habitual es un solo H1 por documento. La sintaxis alternativa "subrayada" (=== / ---) solo sirve para H1 y H2; se prefiere la forma con #.
Énfasis
Negrita, cursiva, ambas
**negrita** y *cursiva* y ***negrita cursiva***negrita y cursiva y negrita cursiva
Los guiones bajos también funcionan (__negrita__, _cursiva_), pero los asteriscos funcionan en medio de una palabra: fan**tás**tico.
Tachado (GFM)
~~texto tachado~~texto tachado
Listas
Sin orden
- Primer elemento
- Segundo elemento
- Anidado (sangría de 2 espacios)
- Tercer elemento- Primer elemento
- Segundo elemento
- Anidado (sangría de 2 espacios)
- Tercer elemento
Ordenada
1. Paso uno
2. Paso dos
1. Los números que escribas no importan: el renderizador cuenta por ti- Paso uno
- Paso dos
- Los números que escribas no importan: el renderizador cuenta por ti
Lista de tareas (GFM)
- [x] Lanzar la función
- [ ] Escribir la documentación
- [ ] Avisarle a alguien- Lanzar la función
- Escribir la documentación
- Avisarle a alguien
Enlaces e imágenes
Enlace en línea
[texto del enlace](https://docs-md.com "título opcional al pasar el cursor")Imagen
Una imagen es un enlace con ! delante. El texto alternativo importa: los lectores de pantalla lo leen y aparece cuando la imagen no carga.
Enlace automático (GFM)
Las URL sueltas se convierten en enlaces: https://docs-md.comLas URL sueltas se convierten en enlaces: https://docs-md.com
Por referencia
Los documentos largos se leen mejor con [referencias con nombre][docs].
[docs]: https://docs-md.comLos documentos largos se leen mejor con referencias con nombre.
Las definiciones pueden ir en cualquier parte del archivo; por convención, al final.
Enlaces a anclas
Un enlace a un encabezado de la misma página. El destino es el texto del encabezado convertido en slug: minúsculas, espacios por guiones y sin puntuación.
Enlazar a un encabezado
## Primeros pasos
Ve a [Primeros pasos](#primeros-pasos) o a [Paso 2: Instalar](#paso-2-instalar).Primeros pasos
Ve a Primeros pasos o a Paso 2: Instalar.
Reglas del slug en GitHub: todo en minúsculas, se quita la puntuación excepto guiones y guiones bajos, los espacios se convierten en guiones y a los encabezados repetidos se les agrega -1, -2. "Paso 2: Instalar" queda como #paso-2-instalar. Las letras con tilde se conservan en minúscula, así que "Instalación" queda como #instalación.
Ancla personalizada con HTML
<a id="destino-personalizado"></a>
## Cualquier texto de encabezado
[Ir allá](#destino-personalizado)Si el texto del encabezado puede cambiar, fija un id explícito con una etiqueta <a> vacía encima. Funciona donde se permita HTML en línea (GitHub, GitLab, la mayoría de los generadores de sitios estáticos).
Código
Código en línea
Ejecuta `npm install` antes de `npm run dev`.Ejecuta npm install antes de npm run dev.
Bloque con lenguaje
```ts
function greet(name: string) {
return `Hello, ${name}`;
}
```function greet(name: string) {
return `Hello, ${name}`;
}
La etiqueta de lenguaje después de ``` activa el resaltado de sintaxis. Etiquetas comunes: js, ts, python, bash, json, sql, diff.
Un bloque dentro de otro
````md
Para mostrar un bloque de código dentro de otro,
usa más comillas invertidas afuera:
```js
console.log("anidado");
```
````Tablas (GFM)
Tabla básica con alineación
| Izquierda | Centro | Derecha |
| :-------- | :----: | ------: |
| a | b | c |
| d | e | f || Izquierda | Centro | Derecha |
|---|---|---|
| a | b | c |
| d | e | f |
Los dos puntos en la fila separadora controlan la alineación. Para escribir una barra vertical literal dentro de una celda, escápala como \|.
Citas
Cita y anidamiento
> Un párrafo citado.
>
> > Las citas anidadas también funcionan.
>
> De vuelta al primer nivel: **el formato funciona adentro**.Un párrafo citado.
Las citas anidadas también funcionan.
De vuelta al primer nivel: el formato funciona adentro.
Pon > al inicio de cada línea (un > solo mantiene unida una cita de varios párrafos). GitHub convierte las citas > [!NOTE] / [!WARNING] en alertas de color.
Alertas (GitHub)
Una cita cuya primera línea es [!TYPE] se muestra en GitHub como un recuadro de color. Hay cinco tipos: NOTE, TIP, IMPORTANT, WARNING y CAUTION. Las palabras clave van en inglés.
Los cinco tipos de alerta
> [!NOTE]
> Información útil que el lector debe conocer.
> [!TIP]
> Un consejo para hacer algo mejor.
> [!IMPORTANT]
> Información clave para lograrlo.
> [!WARNING]
> Información urgente que requiere atención inmediata.
> [!CAUTION]
> Consecuencias negativas de una acción.Nota Información útil que el lector debe conocer.
Consejo Un consejo para hacer algo mejor.
Importante Información clave para lograrlo.
Advertencia Información urgente que requiere atención inmediata.
Precaución Consecuencias negativas de una acción.
Se muestran como recuadros de color con íconos en GitHub (README, issues, pull requests, discusiones) y GitLab. En los demás lugares (vista previa de VS Code, Slack, Discord, Notion, la mayoría de los generadores de sitios estáticos) el texto literal "[!NOTE]" aparece dentro de una cita normal, que es más o menos lo que muestra la vista previa de la derecha.
Estructura y espaciado
Línea horizontal
Arriba de la línea.
---
Debajo de la línea.Arriba de la línea.
Debajo de la línea.
Tres o más guiones solos en una línea, con líneas en blanco alrededor (si no, un --- debajo de un texto lo convierte en H2).
Salto de línea vs. párrafo nuevo
Termina una línea con dos espacios
para un salto de línea en el mismo párrafo.
Una línea en blanco empieza un párrafo nuevo.Termina una línea con dos espacios
para un salto de línea en el mismo párrafo.
Una línea en blanco empieza un párrafo nuevo.
Una barra invertida al final de la línea también fuerza el salto y se ve más fácil que los espacios al final.
Escapar caracteres
\*no es cursiva\* y \# no es encabezado y \| no es barra de tabla*no es cursiva* y # no es encabezado y | no es barra de tabla
Notas al pie (GFM)
Referencia y definición de la nota
Markdown se creó en 2004.[^1]
[^1]: Por John Gruber, con aportes de Aaron Swartz a la sintaxis.Compatible con GitHub y la mayoría de los renderizadores modernos; no forma parte del markdown original.
Emoji
Códigos cortos y emoji literales
Listo para lanzar :tada: :rocket: o pega el carácter directamente: 🎉 🚀Los códigos cortos como :tada: no son markdown: GitHub, GitLab, Slack y Discord los convierten; los renderizadores CommonMark, la vista previa de VS Code y la mayoría de los generadores de sitios estáticos muestran los dos puntos. Pegar el emoji como carácter funciona en todas partes.
Diagramas mermaid
Diagrama de flujo desde un bloque de código
```mermaid
graph LR
A[Escribir markdown] --> B{¿Compartirlo?}
B -->|sí| C[Obtener un enlace]
B -->|no| D[Guardarlo local]
```Compatible con GitHub, GitLab y las páginas compartidas de Docs MD. También admite diagramas de secuencia, diagramas de Gantt y diagramas entidad-relación.
HTML en línea
Cuando markdown no alcanza
Markdown no tiene subrayado, así que usa <u>HTML</u>, <sub>subíndice</sub>, <sup>superíndice</sup> o <kbd>Ctrl</kbd>+<kbd>C</kbd>.Markdown no tiene subrayado, así que usa <u>HTML</u>, <sub>subíndice</sub>, <sup>superíndice</sup> o <kbd>Ctrl</kbd>+<kbd>C</kbd>.
La mayoría de los renderizadores dejan pasar el HTML (GitHub elimina scripts y estilos). La vista previa de esta página quita el HTML sin procesar, así que revisa el resultado en la plataforma de destino.
Teclas con <kbd>
Presiona <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> para abrir la paleta de comandos.GitHub muestra <kbd> como una pequeña tecla. Markdown no tiene sintaxis propia para teclas; las comillas invertidas (`Ctrl`) son la alternativa en texto plano que funciona en todas partes.
Sección desplegable con <details>
<details>
<summary>Haz clic para expandir</summary>
Contenido oculto: **aquí funciona markdown** si dejas una línea en blanco después del summary.
</details>Compatible con GitHub, GitLab y la mayoría de los sitios de documentación. Agrega <details open> para que empiece expandida. No funciona en Slack, Discord ni Notion.
Preguntas frecuentes
¿Qué es una guía rápida de Markdown?
Es una referencia de una página con cada elemento de markdown, su sintaxis y el resultado renderizado lado a lado, para que copies los caracteres exactos en lugar de adivinar. Esta cubre el markdown básico, GitHub Flavored Markdown (tablas, listas de tareas, tachado, notas al pie) y los diagramas mermaid.
¿Cómo pongo texto en negrita o cursiva en markdown?
Encierra el texto entre dos asteriscos para negrita (**negrita**) y entre un asterisco o guion bajo para cursiva (*cursiva* o _cursiva_). Tres asteriscos dan negrita cursiva. En GitHub, los guiones bajos dentro de una palabra no activan el énfasis, así que los asteriscos son la opción más segura.
¿Cómo agrego un enlace o una imagen?
Un enlace es [texto](https://example.com) y una imagen es lo mismo con un signo de exclamación delante: . Para agregar un texto emergente, pon un título entre comillas después de la URL. Los enlaces por referencia ([texto][id] más [id]: url en su propia línea) mantienen legibles los documentos largos.
¿Cómo escribo un bloque de código?
Pon el código entre dos líneas de tres comillas invertidas. Agrega el nombre del lenguaje justo después de las comillas de apertura (```js) para activar el resaltado de sintaxis. Para código en línea, usa una sola comilla invertida a cada lado.
¿Cómo hago una tabla en markdown?
Separa las columnas con barras verticales y agrega una línea de guiones debajo de la fila de encabezado. Los dos puntos en esa línea separadora definen la alineación: :--- izquierda, :---: centro, ---: derecha. Las tablas son una extensión de GFM compatible con GitHub, GitLab y la mayoría de los renderizadores.
¿Cuál es la diferencia entre Markdown y GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) es el markdown original más tablas, listas de tareas, tachado, enlaces automáticos y notas al pie, con una especificación formal basada en CommonMark. Casi todos los renderizadores modernos soportan GFM, así que es lo que la gente suele llamar "markdown". GitHub además agrega alertas, códigos cortos de emoji y mermaid sobre GFM.
¿Qué Markdown funciona en Slack, Discord y Notion?
Cada uno usa una variante distinta. Discord admite casi todo lo básico (**negrita**, *cursiva*, bloques de código, encabezados, citas), pero no tiene tablas ni imágenes y usa __guiones bajos__ para subrayar. Slack no es markdown: *un asterisco* es negrita, _guiones bajos_ cursiva, ~virgulillas~ tachado, y los enlaces [texto](url) solo funcionan en el cuadro de mensaje con la preferencia de marcado activada. Notion convierte el markdown mientras escribes y al pegar, incluidas tablas y listas de tareas.
¿Cómo hago un salto de línea en markdown?
Un solo Enter no basta: las dos líneas se unen en el mismo párrafo. Termina la línea con una barra invertida o con dos espacios para un salto de línea, o deja una línea en blanco para empezar un párrafo nuevo.
¿Con qué abro un archivo .md para ver el resultado?
Cualquier editor de texto muestra la sintaxis sin formato. Para ver el resultado renderizado, abre el archivo en un visor de markdown en el navegador, como el de Docs MD, o usa la vista previa de un editor como Visual Studio Code.