Guía de Markdown para escritores y desarrolladores
Domina la sintaxis de Markdown desde lo básico hasta funciones avanzadas: tablas, bloques de código, listas de tareas y las diferencias entre los distintos sabores de Markdown.
Markdown es lo más parecido que existe en internet a un formato de escritura universal. Se usa en READMEs de GitHub, documentos de Notion, mensajes de Slack, sitios de documentación, entradas de blog y notas de desarrolladores. Aprénde lo una vez y lo usarás en todas partes — durante el resto de tu carrera.
¿Qué es Markdown?
Markdown es un lenguaje de marcado ligero creado por John Gruber en 2004. La idea central: escribir en texto plano usando convenciones de puntuación simples, y este se renderiza como HTML con un formato impecable.
This **bold text** and *italic text* render instantly.
Se renderiza como: This bold text and italic text render instantly.
El texto sin procesar sigue siendo perfectamente legible, incluso antes de renderizarse.
Sintaxis básica
Encabezados
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Usa encabezados para crear una jerarquía en el documento. # H1 suele ser el título de la página — usa solo uno por documento.
Énfasis
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
Listas
Unordered list:
- Item one
- Item two
- Nested item (indent with 2 spaces)
- Another nested item
- Item three
Ordered list:
1. First step
2. Second step
3. Third step
Enlaces e imágenes
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
Citas en bloque
> This is a blockquote.
> It can span multiple lines.
> You can nest blockquotes:
> > Like this.
Línea horizontal
---
(Tres o más guiones, asteriscos o guiones bajos en su propia línea)
Bloques de código
El código en línea usa comillas invertidas simples:
Use the `console.log()` function for debugging.
Los bloques de código delimitados usan triple comilla invertida con un identificador de lenguaje opcional para el resaltado de sintaxis:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
Los lenguajes compatibles incluyen javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust y docenas más, según el renderizador.
Tablas
Las tablas en Markdown usan caracteres de barra vertical y guiones:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A | Cell B | Cell C |
| Cell D | Cell E | Cell F |
Alinea las columnas con dos puntos en la fila separadora:
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
Las tablas forman parte de GitHub Flavored Markdown (GFM), no del Markdown estándar. Funcionan en GitHub, VS Code, la mayoría de las plataformas de documentación y MDX.
Listas de tareas (GFM)
- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images
Se renderiza como casillas de verificación interactivas en GitHub. Compatible con la mayoría de los renderizadores modernos de Markdown.
Sabores de Markdown
El Markdown original es intencionalmente minimalista. Con el tiempo han proliferado diversas extensiones:
| Sabor | Usado en | Características principales |
|---|---|---|
| CommonMark | Muchas plataformas | Especificación estandarizada |
| GitHub Flavored (GFM) | GitHub, GitLab | Tablas, listas de tareas, tachado, autoenlaces |
| MDX | Sitios con React | Componentes JSX dentro de Markdown |
| Pandoc Markdown | Documentos académicos | Notas al pie, citas, fórmulas matemáticas |
| MultiMarkdown | Herramientas macOS | Tablas, metadatos, notas al pie |
En caso de duda, usa GFM — es el sabor extendido con mayor compatibilidad.
Front matter
Muchos procesadores de Markdown admiten YAML front matter al inicio de un archivo para incluir metadatos:
---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---
# Article content starts here
El front matter se analiza por separado del cuerpo del documento y se utiliza para cosas como títulos de página, fechas y metadatos SEO.
MDX: Markdown + JSX
MDX es Markdown que puede contener componentes de React. Es ideal para documentación y entradas de blog en sitios basados en React (Next.js, Gatsby, Astro):
import { Alert } from '../components/Alert'
## Important note
<Alert type="warning">
This feature is deprecated in v3.
</Alert>
Regular **Markdown** content continues below.
Esto combina la simplicidad de Markdown con la potencia de los componentes interactivos.
Escapar caracteres especiales
Precede los caracteres especiales de Markdown con una barra invertida para renderizarlos literalmente:
\*not italic\*
\# not a heading
\[not a link\]
Consejos para mejores documentos en Markdown
- Una oración por línea — Hace que los diffs sean más claros en Git; se renderiza de forma idéntica, ya que Markdown ignora los saltos de línea simples.
- Línea en blanco entre bloques — Deja siempre una línea en blanco entre párrafos, encabezados, listas y bloques de código.
- Marcadores de lista coherentes — Elige
-o*para las listas desordenadas y mantenlo en todo el proyecto. - Enlaces de referencia para URLs repetidas — Defínelos una vez, úsalos muchas veces:
See the [documentation][docs] and [changelog][docs]. [docs]: https://example.com/docs - Texto alternativo para cada imagen — Esencial para la accesibilidad y el SEO.
Verificar la legibilidad
Markdown facilita la escritura, pero escribir con facilidad puede producir textos difíciles de leer. Usa nuestra herramienta Readability Score para comprobar el nivel de grado Flesch-Kincaid, la complejidad de las oraciones y el uso de la voz pasiva. Apunta a un lenguaje claro y conciso con un nivel de lectura de grado 8–10 para audiencias generales.
Markdown es una de esas herramientas que se aprenden en 10 minutos y generan beneficios de por vida. Empieza a escribir en Markdown hoy mismo — tus futuros colaboradores (y tu yo del futuro) te lo agradecerán.