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.

Sintaxis básica

Encabezados

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.

Pá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 <br>.

É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).

Listas

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.

Enlaces e imágenes

[Texto visible del enlace](https://ejemplo.com)
[Enlace con título](https://ejemplo.com "Título al hacer hover")

![Texto alt de la imagen](ruta/imagen.png)
![Logo](logo.png "Texto del título")

Para enlaces que se repiten, puedes usar referencias:

[Google][1] y [GitHub][2] son sitios útiles.

[1]: https://google.com
[2]: https://github.com

Có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.

Citas (Blockquotes)

> Esta es una cita.
> Puede ocupar varias líneas.
>
> > Y puedes anidar citas dentro de citas.

Líneas horizontales

Tres o más guiones, asteriscos o guiones bajos crean una línea divisoria:

---
***
___

Sintaxis avanzada

Tablas

| 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.

Listas de tareas (GitHub Flavored Markdown)

- [x] Tarea completada
- [x] Otra tarea terminada
- [ ] Tarea pendiente
- [ ] Otra pendiente

Notas al pie

Este es un texto con nota al pie[^1].

[^1]: Esta es la nota al pie.

Texto 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.

Plataformas que usan Markdown

GitHub

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).

Documentación técnica

Docusaurus, GitBook, MkDocs, Sphinx, VitePress — los principales generadores de documentación usan Markdown como formato de entrada.

Blogs 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.

Aplicaciones de notas

Obsidian, Notion, Bear, Typora, iA Writer, Logseq — las mejores herramientas de productividad personal soportan o se basan en Markdown.

Comunicación

Slack, Discord, Microsoft Teams, Telegram — permiten formateo básico con sintaxis Markdown o similar.

Consejos profesionales

1. Sé consistente. Elige una convención (asteriscos vs guiones bajos, guiones vs asteriscos para listas) y mantenla en todo el documento.
2. Usa headings semánticos. No saltes niveles (de H2 a H4 sin H3). Esto afecta la accesibilidad y la generación de tabla de contenidos.
3. Mantén líneas cortas. Aunque Markdown no lo requiere, líneas de 80-120 caracteres son más fáciles de leer en editores y diffs de Git.
4. Añade alt text a las imágenes. Es fundamental para accesibilidad y para que el contenido sea comprensible sin las imágenes.
5. Usa linters. Herramientas como markdownlint verifican tu Markdown contra reglas de estilo consistentes.

Markdown vs HTML: cuando usar cada uno

Markdown no reemplaza HTML, lo complementa. Para documentacion, READMEs, artículos de blog, notas personales y comunicacion en plataformas tecnicas, Markdown es mas rapido y legible. Para interfaces web complejas con formularios, layouts responsivos, elementos interactivos o estilos avanzados, HTML sigue siendo necesario.

La mayoria de procesadores de Markdown permiten insertar HTML directamente cuando necesitas algo que Markdown no cubre. Por ejemplo, puedes usar una etiqueta div con estilos para centrar una imagen, o una tabla HTML compleja con celdas fusionadas que las tablas de Markdown no soportan. Sin embargo, mezclar demasiado HTML con Markdown reduce la legibilidad del fuente, que es precisamente la ventaja principal de Markdown.

En la practica, la regla es simple: usa Markdown para todo lo que puedas y recurre a HTML solo cuando Markdown no ofrezca la funcionalidad que necesitas. Si te encuentras escribiendo mas HTML que Markdown, probablemente debas usar HTML directamente o considerar un generador de sitios que ofrezca componentes reutilizables.

Variantes de Markdown: CommonMark, GFM y mas

Uno de los problemas historicos de Markdown es la ambiguedad de la especificacion original de Gruber. Casos como listas anidadas, HTML dentro de Markdown o multiples lineas en blanco se interpretaban de forma diferente segun el procesador. Esto llevo a la creacion de CommonMark, una especificacion rigurosa y completa que elimina ambiguedades.

GitHub Flavored Markdown (GFM) extiende CommonMark con funcionalidades especificas: tablas, listas de tareas, tachado, autolinks, alertas (note, tip, warning) y mencion de usuarios. Si escribes para GitHub, GFM es tu referencia.

Otras variantes notables incluyen MultiMarkdown (MMD), que añade notas al pie, tablas avanzadas, citaciones bibliograficas y metadatos; Pandoc Markdown, que soporta practicamente cualquier extension imaginable y puede convertir entre docenas de formatos; y R Markdown, que integra bloques de codigo R ejecutable para informes reproducibles en ciencia de datos.

Para garantizar compatibilidad maxima, escribe siguiendo CommonMark como base y añade extensiones de GFM solo cuando publiques en plataformas que las soporten.

Editores de Markdown recomendados en 2026

La eleccion del editor puede transformar tu experiencia con Markdown. Estos son los mas recomendados segun el caso de uso:

Para notas y conocimiento personal: Obsidian es el lider indiscutible. Almacena todo en archivos .md locales, soporta backlinks entre notas, grafos de conocimiento, plugins comunitarios y sincronizacion entre dispositivos. Su comunidad es enorme y activa, con miles de plugins y temas disponibles.

Para escritura enfocada: iA Writer y Typora ofrecen interfaces minimalistas que eliminan distracciones. iA Writer destaca por su modo de enfoque que atenua todo excepto la frase actual. Typora renderiza el Markdown en tiempo real dentro del mismo editor, eliminando la necesidad de un panel de previsualizacion separado.

Para desarrolladores: Visual Studio Code con las extensiones Markdown All in One y Markdown Preview Enhanced ofrece la mejor experiencia integrada en un entorno de desarrollo. Puedes escribir documentacion junto al codigo, con previsualizacion en vivo, linting y atajos de teclado para todas las operaciones comunes.

Para equipos y documentacion publica: Notion y GitBook combinan la facilidad de Markdown con funcionalidades colaborativas como comentarios, permisos de acceso y publicacion web. Notion usa una variante propia de Markdown que se traduce a bloques internos, mientras que GitBook trabaja directamente con archivos .md en repositorios Git.

Flujos de trabajo avanzados con Markdown

Generacion de sitios estaticos

Los generadores de sitios estaticos como Hugo, Astro, Next.js y Eleventy transforman archivos Markdown en paginas HTML completas con layouts, navegacion, SEO y estilos. Escribes contenido en Markdown, defines metadatos en frontmatter YAML al inicio del archivo (titulo, fecha, categorias, tags) y el generador produce un sitio web optimizado listo para desplegar.

Este flujo es especialmente popular para blogs tecnicos, documentacion de proyectos open source y portfolios personales. La ventaja es que el contenido vive en archivos de texto plano versionables con Git, lo que facilita la colaboracion, el historial de cambios y la portabilidad.

Presentaciones con Markdown

Herramientas como Marp, Slidev y Reveal.js permiten crear presentaciones profesionales escribiendo en Markdown. Cada separador (---) marca una nueva diapositiva. Puedes incluir imagenes, bloques de codigo con syntax highlighting, diagramas Mermaid y formulas matematicas LaTeX, todo sin tocar PowerPoint ni Google Slides.

Documentacion como codigo

El movimiento "docs as code" trata la documentacion con las mismas practicas que el codigo fuente: versionado con Git, revisiones mediante pull requests, integracion continua para validar enlaces rotos y despliegue automatico. Markdown es el formato natural para este enfoque porque es texto plano, compatible con diff, facil de escribir y de revisar.

Conclusió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.