Markdown: guía completa de sintaxis para principiantes y expertos
Qué es Markdown?
Markdown es un lenguaje de marcado ligero creado por John Gruber y Aaron Swartz en 2004. Su filosofía fundamental es que el texto fuente debe ser legible tal cual, sin renderizar — a diferencia de HTML, donde las etiquetas dificultan la lectura directa.
Hoy Markdown es omnipresente: GitHub lo usa para READMEs, issues y pull requests; Reddit para comentarios; Notion, Obsidian y Bear para notas; Hugo, Jekyll y Gatsby para blogs estáticos; Jupyter para documentación de notebooks; y prácticamente toda la documentación técnica moderna se escribe en Markdown.
Su éxito se basa en un equilibrio perfecto entre simplicidad y expresividad. Con unas pocas reglas intuitivas puedes crear documentos bien formateados que funcionan en cientos de plataformas.
intaxis básica
ncabezados
Usa almohadillas (#) para crear títulos jerárquicos. Más almohadillas = nivel menor:
# Título principal (H1)
## Sección (H2)
### Subsección (H3)
#### Sub-subsección (H4)
##### Nivel 5 (H5)
###### Nivel 6 (H6)
En la práctica, raramente necesitarás más allá de H3. Un documento bien estructurado usa H1 para el título del documento, H2 para secciones principales y H3 para subsecciones.
árrafos y saltos de línea
Los párrafos se separan con una línea en blanco. Para un salto de línea dentro del mismo párrafo, añade dos espacios al final de la línea o usa
nfasis
*cursiva* o _cursiva_
**negrita** o __negrita__
***negrita cursiva*** o ___negrita cursiva___
~~tachado~~ (extensión GitHub)
Convención recomendada: usa asteriscos (*) para énfasis y reserva guiones bajos (_) para cuando los asteriscos causan conflictos (por ejemplo, dentro de palabras).
istas
Listas desordenadas — usa -, * o +:
- Primer elemento
- Segundo elemento
- Sub-elemento (indentado con 2 espacios)
- Otro sub-elemento
- Tercer elemento
Listas ordenadas:
1. Primer paso
2. Segundo paso
3. Tercer paso
Dato interesante: Markdown numera las listas automáticamente. Puedes escribir todos los elementos con 1. y se numerarán correctamente al renderizar.
nlaces e imágenes
[Texto visible del enlace](https://ejemplo.com)
[Enlace con título](https://ejemplo.com "Título al hacer hover")
Para enlaces que se repiten, puedes usar referencias:
[Google][1] y [GitHub][2] son sitios útiles.
[1]: https://google.com
[2]: https://github.com
ódigo
Para código en línea, enciérralo en backticks: console.log("hola")
Para bloques de código, usa triple backtick con el lenguaje para syntax highlighting:
\`\`\`javascript
function saludar(nombre) {
return "Hola, " + nombre;
}
\`\`\`
Lenguajes soportados comunes: javascript, typescript, python, java, go, rust, html, css, bash, sql, json, yaml, markdown.
itas (Blockquotes)
> Esta es una cita.
> Puede ocupar varias líneas.
>
> > Y puedes anidar citas dentro de citas.
íneas horizontales
Tres o más guiones, asteriscos o guiones bajos crean una línea divisoria:
---
***
___
intaxis avanzada
ablas
| Columna 1 | Columna 2 | Columna 3 |
|-----------|:---------:|----------:|
| Izquierda | Centro | Derecha |
| Dato 1 | Dato 2 | Dato 3 |
Los dos puntos en la línea separadora controlan la alineación: :- izquierda, :-: centro, -: derecha.
istas de tareas (GitHub Flavored Markdown)
- [x] Tarea completada
- [x] Otra tarea terminada
- [ ] Tarea pendiente
- [ ] Otra pendiente
otas al pie
Este es un texto con nota al pie[^1].
[^1]: Esta es la nota al pie.
exto colapsable (GitHub)
<details>
<summary>Haz clic para expandir</summary>
Contenido oculto que se muestra al hacer clic.
</details>
Dónde practicar Markdown?
La mejor forma de aprender Markdown es usándolo activamente. Con nuestro conversor de Markdown a HTML puedes escribir Markdown en el panel izquierdo y ver el resultado renderizado en tiempo real en el panel derecho. Es perfecto para experimentar con la sintaxis y ver instantáneamente cómo se renderiza cada elemento.
lataformas que usan Markdown
itHub
README.md, CONTRIBUTING.md, issues, pull requests, comentarios, wikis, GitHub Pages — todo en GitHub acepta Markdown. GitHub Flavored Markdown (GFM) añade extensiones como tablas, listas de tareas, alertas y mención de usuarios (@usuario).
ocumentación técnica
Docusaurus, GitBook, MkDocs, Sphinx, VitePress — los principales generadores de documentación usan Markdown como formato de entrada.
logs y CMS
Hugo, Jekyll, Gatsby, Next.js, Astro, Eleventy — los generadores de sitios estáticos más populares procesan archivos .md como páginas o artículos.
plicaciones de notas
Obsidian, Notion, Bear, Typora, iA Writer, Logseq — las mejores herramientas de productividad personal soportan o se basan en Markdown.
omunicación
Slack, Discord, Microsoft Teams, Telegram — permiten formateo básico con sintaxis Markdown o similar.
onsejos profesionales
onclusión
Markdown es una habilidad esencial para cualquier persona que trabaje con tecnología, documentación o contenido digital. Con unas pocas reglas simples puedes crear contenido bien formateado, legible y portable que funciona en cientos de plataformas. Practica con nuestro conversor de Markdown a HTML y domina la sintaxis en cuestión de minutos.