Hoja de Referencia de Markdown: Guía Completa
· 12 min de lectura
Markdown se ha convertido en el lenguaje universal de formato de texto en la web. Ya sea que estés escribiendo documentación en GitHub, publicando en Reddit, chateando en Discord, organizando notas en Notion o creando contenido para innumerables otras plataformas, Markdown está en todas partes. Aprender esta sintaxis simple pero poderosa te hará más productivo en cada espacio de trabajo digital que uses.
Esta guía completa cubre todo, desde el formato básico hasta técnicas avanzadas, con ejemplos prácticos y casos de uso del mundo real. Guarda esta página como tu referencia principal para todo lo relacionado con Markdown.
📑 Tabla de Contenidos
- ¿Qué es Markdown y por qué usarlo?
- Formato Básico de Texto
- Encabezados y Estructura del Documento
- Listas: Ordenadas, Desordenadas y Anidadas
- Enlaces e Imágenes
- Bloques de Código y Resaltado de Sintaxis
- Creación de Tablas
- Citas en Bloque y Referencias
- Características Avanzadas de Markdown
- Variantes y Extensiones de Markdown
- Mejores Prácticas y Errores Comunes
- Preguntas Frecuentes
¿Qué es Markdown y por qué usarlo?
Markdown es un lenguaje de marcado ligero creado por John Gruber en 2004. Su filosofía es simple: el texto plano debe ser legible tal como está, pero también convertible a HTML y otros formatos. A diferencia de los editores de texto enriquecido que ocultan el formato detrás de botones y menús, Markdown mantiene todo visible y portátil.
La belleza de Markdown radica en su simplicidad. Puedes escribirlo en cualquier editor de texto, controlarlo con Git y convertirlo a HTML, PDF o docenas de otros formatos. Se ha convertido en el estándar de facto para documentación técnica, archivos README, publicaciones de blog y escritura colaborativa.
Dónde se usa Markdown:
- GitHub, GitLab y Bitbucket para archivos README y documentación
- Reddit, Discord y Slack para mensajes formateados
- Notion, Obsidian y Roam Research para tomar notas
- Generadores de sitios estáticos como Jekyll, Hugo y Gatsby
- Sistemas de gestión de contenido y plataformas de blogs
- Herramientas de escritura técnica y plataformas de documentación
Consejo profesional: Usa nuestro Editor de Markdown gratuito para practicar la sintaxis en tiempo real con vista previa en vivo. Es la forma más rápida de aprender haciendo.
Formato Básico de Texto
La sintaxis de formato básico de Markdown es intuitiva y fácil de recordar. La mayoría del formato usa caracteres especiales que rodean el texto que deseas estilizar.
Texto en Negrita
Crea texto en negrita envolviendo palabras con dobles asteriscos o dobles guiones bajos:
**Este texto está en negrita**
__Esto también está en negrita__
Ambos producen: Este texto está en negrita
Texto en Cursiva
Usa asteriscos simples o guiones bajos simples para texto en cursiva:
*Este texto está en cursiva*
_Esto también está en cursiva_
Ambos producen: Este texto está en cursiva
Negrita y Cursiva Combinadas
Combina ambos usando tres asteriscos o mezclando asteriscos y guiones bajos:
***Texto en negrita y cursiva***
**_También en negrita y cursiva_**
Resultado: Texto en negrita y cursiva
Tachado
La mayoría de las variantes de Markdown admiten tachado con dobles tildes:
~~Este texto está tachado~~
Resultado: Este texto está tachado
Código en Línea
Envuelve el texto en comillas invertidas simples para formatearlo como código en línea:
Usa la función `console.log()` para depurar.
Resultado: Usa la función console.log() para depurar.
| Sintaxis | Resultado | Caso de Uso |
|---|---|---|
**texto** |
texto | Énfasis, términos importantes |
*texto* |
texto | Énfasis sutil, títulos de libros |
~~texto~~ |
Contenido eliminado, correcciones | |
`texto` |
texto |
Código, comandos, nombres de archivo |
Encabezados y Estructura del Documento
Los encabezados crean jerarquía en el documento y mejoran la legibilidad. Markdown admite seis niveles de encabezados, coincidiendo con las etiquetas <h1> hasta <h6> de HTML.
# Encabezado 1 (Más grande)
## Encabezado 2
### Encabezado 3
#### Encabezado 4
##### Encabezado 5
###### Encabezado 6 (Más pequeño)
El número de símbolos de almohadilla determina el nivel del encabezado. Siempre incluye un espacio entre los símbolos de almohadilla y el texto del encabezado.
Mejor práctica: Usa los niveles de encabezado jerárquicamente. No saltes de H1 a H4. Esto mejora la accesibilidad para lectores de pantalla y ayuda a los motores de búsqueda a entender la estructura de tu contenido.
Sintaxis Alternativa de Encabezados
Para H1 y H2, también puedes usar sintaxis de estilo subrayado:
Encabezado 1
=========
Encabezado 2
---------
Sin embargo, la sintaxis con símbolos de almohadilla es más común y admite los seis niveles.
Mejores Prácticas para Encabezados
- Usa solo un H1 por documento (típicamente el título)
- Mantén los encabezados concisos y descriptivos
- Usa mayúsculas de oración o título de forma consistente
- No termines los encabezados con puntuación
- Agrega líneas en blanco antes y después de los encabezados para legibilidad
Listas: Ordenadas, Desordenadas y Anidadas
Las listas son fundamentales para organizar información. Markdown admite listas desordenadas (con viñetas), listas ordenadas (numeradas) y combinaciones anidadas de ambas.
Listas Desordenadas
Crea listas con viñetas usando asteriscos, guiones o signos de más. Los tres producen resultados idénticos:
* Primer elemento
* Segundo elemento
* Tercer elemento
- Primer elemento
- Segundo elemento
- Tercer elemento
+ Primer elemento
+ Segundo elemento
+ Tercer elemento
Elige un estilo y mantenlo en todo tu documento para consistencia.
Listas Ordenadas
Numera tus elementos de lista con puntos. Los números reales no importan—Markdown los renumerará automáticamente:
1. Primer elemento
2. Segundo elemento
3. Tercer elemento
1. Primer elemento
1. Segundo elemento
1. Tercer elemento
Ambos producen la misma lista numerada. Usar todos 1s facilita reordenar elementos sin renumerar.
Listas Anidadas
Indenta los elementos anidados con 2 o 4 espacios (sé consistente):
1. Primer elemento
- Viñeta anidada
- Otra viñeta anidada
2. Segundo elemento
1. Número anidado
2. Otro número anidado
Listas de Tareas
Muchas variantes de Markdown admiten listas de tareas con casillas de verificación:
- [x] Tarea completada
- [ ] Tarea incompleta
- [ ] Otra tarea incompleta
Esto es particularmente útil en issues de GitHub y herramientas de gestión de proyectos.
Consejo rápido: Al escribir elementos de lista de varios párrafos, indenta los párrafos subsiguientes para alinearlos con la primera línea de texto, no con la viñeta.
Enlaces e Imágenes
Markdown facilita agregar hipervínculos e imágenes sin saturar tu texto con etiquetas HTML.
Enlaces Básicos
La sintaxis para enlaces es sencilla: corchetes para el texto del enlace, seguidos de paréntesis para la URL:
[Visita nuestro Editor de Markdown](/tools/markdown-editor/)
Resultado: Visita nuestro Editor de Markdown
Enlaces con Títulos
Agrega un atributo de título (mostrado al pasar el cursor) incluyéndolo entre comillas después de la URL:
[GitHub](https://github.com "Visita GitHub")
Enlaces de Estilo Referencia
Para documentos con muchos enlaces repetidos, usa sintaxis de estilo referencia para mantener tu texto limpio:
Consulta [Google][1] y [GitHub][2] para más información.
[1]: https://google.com "Google"
[2]: https://github.com "GitHub"
Las definiciones de referencia pueden aparecer en cualquier parte del documento y no serán visibles en el resultado.
Enlaces Automáticos
Envuelve URLs o direcciones de correo electrónico en corchetes angulares para hacerlas clicables:
<https://example.com>
<email@example.com>
Muchos procesadores de Markdown también enlazan automáticamente URLs sin corchetes angulares.
Imágenes
La sintaxis de imagen es idéntica a los enlaces, pero con un signo de exclamación como prefijo:


El texto alternativo es crucial para accesibilidad y SEO. Siempre proporciona texto alternativo descriptivo que explique qué muestra la imagen.
Mejores Prácticas para Imágenes
- Escribe texto alternativo descriptivo para accesibilidad
- Usa rutas relativas para imágenes en el mismo repositorio
- Optimiza los tamaños de archivo de imagen para carga más rápida
- Considera usar sintaxis de estilo referencia para imágenes repetidas
- Prueba que las imágenes se muestren correctamente en tu plataforma objetivo
Bloques de Código y Resaltado de Sintaxis
Los bloques de código son esenciales para documentación técnica. Markdown proporciona múltiples formas de formatear código, desde fragmentos en línea hasta bloques de múltiples líneas con resaltado de sintaxis.
Código en Línea
Como se mencionó anteriormente, envuelve el código en línea en comillas invertidas simples:
Usa el comando `git commit` para guardar cambios.
Bloques de Código Delimitados
Para código de múltiples líneas, usa triples comillas invertidas (o triples tildes) antes y después del código:
```
function greet(name) {
return `Hello, ${name}!`;
}
```
Resaltado de Sintaxis
Especifica el lenguaje de programación después de las comillas invertidas de apertura para resaltado de sintaxis:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
```python
def greet(name):
return f"Hello, {name}!"
```
```css
.button {
background-color: #06b6d4;
border-radius: 8px;
}
```
La mayoría de los procesadores de Markdown admiten docenas de lenguajes incluyendo JavaScript, Python, Java, C++, Ruby, Go, Rust, SQL, HTML, CSS y muchos más.
Bloques de Código Indentados
Una sintaxis más antigua usa indentación de 4 espacios para crear bloques de código:
function example() {
return true;
}
Sin embargo, los bloques de código delimitados son preferidos porque admiten resaltado de sintaxis y son más fáciles de leer en texto plano.
Consejo profesional: Usa nuestro Embellecedor de HTML para formatear código antes de pegarlo en documentos Markdown. El código limpio y bien formateado es más fácil de leer y mantener.
Creación de Tablas
Las tablas organizan datos en filas y columnas. Aunque las tablas de Markdown no son tan flexibles como las tablas HTML, son perfectas para presentación de datos simple.
Sintaxis Básica de Tablas
Crea tablas usando barras verticales y guiones:
| Encabezado 1 | Encabezado 2 | Encabezado 3 |
|--------------|--------------|--------------|
| Celda 1 | Celda 2 | Celda 3 |
| Celda 4 | Celda 5 | Celda 6 |
Las barras verticales no necesitan alinearse perfectamente—los procesadores de Markdown las formatearán correctamente. Sin embargo, las barras alineadas hacen que las tablas sean más fáciles de leer en texto plano.
Alineación de Columnas
Controla la alineación del texto usando dos puntos en la fila separadora:
| Alineado izquierda | Centrado | Alineado derecha |
|:-------------------|:--------:|-----------------:|
| Texto | Texto | Texto |
| Más texto | Más texto| Más texto |
:---alinea a la izquierda (predeterminado):---:centra el texto---:alinea a la derecha
Ejemplo Práctico de Tabla
| Variante de Markdown | Tablas | Listas de Tareas | Notas al pie |
|---|---|---|---|
| CommonMark | ❌ No | ❌ No |