La mayoría de los documentos empiezan como un archivo de texto plano con algunos asteriscos y numerales. Ese archivo suele ser Markdown. No es la única forma de escribir para la web, pero es el formato por defecto para READMEs, seguimiento de issues, chatbots y sitios estáticos, porque la fuente se puede leer antes de renderizarse.
Este artículo es un tutorial rápido y práctico. Asume que tienes diez minutos y un editor de texto. No se necesita instalación.
Qué es Markdown
Markdown es una sintaxis de marcado ligera. John Gruber publicó la especificación original en 2004 con un objetivo: un formato que se viera bien en texto plano y se convirtiera limpiamente a HTML. Desde entonces se ha convertido en el formato de entrada de GitHub, Obsidian, Notion, muchos generadores de sitios estáticos y la mayoría de las salidas de modelos de lenguaje grandes.
La idea central es simple. Marca la estructura con signos de puntuación en lugar de etiquetas:
# Este es un encabezado
Este es un párrafo.
- Este es un elemento de lista
- Este es otro elemento
Un analizador convierte eso en HTML. Diferentes analizadores admiten diferentes extensiones, y ahí es donde entran los estándares.
Los estándares de Markdown importan
Markdown no tiene un único estándar oficial. La especificación original de Gruber deja lagunas que diferentes herramientas han llenado de forma incompatible. Si escribes una tabla en una aplicación y la pegas en otra, puede romperse. Debes saber a qué sabor te diriges.
- CommonMark. Una especificación estricta y bien probada que comenzó en 2014. Define la sintaxis principal con precisión. Si quieres portabilidad, escribe CommonMark.
- GitHub Flavored Markdown (GFM). Añade tablas, listas de tareas, tachados, bloques de código cercados y autolinks. Es lo que ves en los README y comentarios de issues de GitHub.
- Pandoc Markdown. Añade citas, notas al pie, listas de definiciones, subíndices, superíndices y matemáticas. Común en escritura académica.
- Obsidian / Quarto / MDX. Añaden wikilinks, callouts, celdas de código ejecutables o componentes embebidos. Son potentes pero poco portables.
Para el trabajo diario, GFM es el objetivo más seguro. Para documentos extensos que puedan moverse entre herramientas, es mejor CommonMark más un conjunto documentado de extensiones.
Bases de Markdown
Encabezados
Usa de uno a seis numerales. Uno es el más grande.
# Encabezado 1
## Encabezado 2
### Encabezado 3
Párrafos y saltos de línea
Separa los párrafos con una línea en blanco. Termina una línea con dos espacios o una barra invertida para forzar un salto de línea.
Este es el primer párrafo.
Este es el segundo.
Énfasis
_cursiva_ o _cursiva_
**negrita** o **negrita**
**_negrita y cursiva_**
~~tachado~~ (solo GFM)
Listas
Las listas desordenadas usan -, * o +:
- Elemento uno
- Elemento dos
- Elemento anidado
Las listas ordenadas usan números:
1. Paso uno
2. Paso dos
3. Paso tres
Los números no tienen que ser correctos. Markdown los renumera al renderizar. Aun así, usa números secuenciales para que la fuente sea legible.
Enlaces e imágenes
[Texto del enlace](https://example.com)
[Enlace con título](https://example.com "Título")
Para enlaces internos, usa rutas relativas:
[Convertir Markdown a PDF](/tools/markdown-to-pdf)
Código
El código en línea usa backticks simples: `console.log("hi")`.
Los bloques de código usan tres backticks:
```python
def hello():
return "hello"
```
Añade un identificador de idioma después de los backticks de apertura para que el resaltado de sintaxis funcione.
## Trucos comunes y ejemplos
### Citas
```markdown
> Esto es una cita.
> Puede extenderse por varias líneas.
Puedes anidarlas:
> Cita exterior
>
> > Cita anidada
Líneas horizontales
---
Usa tres o más guiones, asteriscos o guiones bajos solos en una línea.
Listas de tareas
GFM admite casillas de verificación:
- [x] Escribir el borrador
- [ ] Revisar las tablas
- [ ] Publicar el artículo
Se renderizan como casillas deshabilitadas en HTML. No las uses como sustituto de entradas de formulario reales.
Escapar caracteres
Prefija los caracteres Markdown con una barra invertida cuando quieras que aparezcan literalmente:
\*no es cursiva\*
\# no es un encabezado
Trucos avanzados y ejemplos
Tablas
Las tablas son una extensión de GFM, no parte de la especificación original de Markdown.
| Característica | CommonMark | GFM |
| ---------------- | ---------- | --- |
| Tablas | No | Sí |
| Listas de tareas | No | Sí |
La alineación es opcional:
| Izquierda | Centro | Derecha |
| :-------- | :----: | ------: |
| A | B | C |
Mantén las tablas simples. Las tablas anidadas, la combinación de filas y columnas no son estándar y a menudo fallan.
Notas al pie
Pandoc y algunos analizadores GFM admiten notas al pie:
Aquí hay una afirmación.[^1]
[^1]: Este es el texto de la nota al pie.
Si necesitas notas al pie en un PDF renderizado, usa un convertidor que admita la sintaxis de Pandoc o insértalas manualmente.
Matemáticas
Pandoc y muchos editores modernos admiten matemáticas LaTeX:
Matemática en línea: $E = mc^2$
Matemática en bloque:
$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$
El renderizado matemático depende del analizador y del formato de salida. HTML suele necesitar MathJax o KaTeX. Los convertidores a PDF a menudo necesitan un backend de LaTeX.
Listas de definiciones
Otra extensión de Pandoc:
Término
: Definición del término.
Otro término
: Otra definición.
HTML dentro de Markdown
Cuando Markdown se queda corto, puedes recurrir a HTML:
<p style="color: red;">Este texto es rojo.</p>
Esto funciona para diseño, videos embebidos o atributos que Markdown no admite. Pero reduce la portabilidad, así que úsalo con moderación.
Cuándo convertir Markdown
Markdown es excelente para escribir y control de versiones. Es malo para documentos finales que deben verse idénticos en todas partes. Por eso existen convertidores.
Si tienes un borrador de Markdown que debe convertirse en un PDF compartible, usa el convertidor de Markdown a PDF. Funciona en el navegador, así que tu archivo nunca abandona tu máquina.
Si partes de un PDF y quieres Markdown editable, usa el convertidor de PDF a Markdown. Extrae encabezados, listas y párrafos sin subir nada a un servidor.
Chuleta de Markdown
| Elemento | Sintaxis | Salida de ejemplo |
|---|---|---|
| Encabezado 1 | # H1 | H1 |
| Encabezado 2 | ## H2 | H2 |
| Encabezado 3 | ### H3 | H3 |
| Negrita | **bold** | bold |
| Cursiva | *italic* | italic |
| Tachado | ~~text~~ | |
| Código en línea | `code` | code |
| Enlace | [text](url) | text |
| Imagen |  | imagen |
| Cita | > quote | cita |
| Lista desordenada | - item | elemento de lista |
| Lista ordenada | 1. item | elemento de lista |
| Línea horizontal | --- | línea horizontal |
| Bloque de código | ```lang | bloque con resaltado |
| Lista de tareas | - [ ] task | casilla de verificación |
| Tabla | | a | b | | tabla |
Imprime esta tabla, pégala junto a tu monitor y raramente necesitarás buscar la sintaxis de Markdown de nuevo.
Notas finales
Markdown recompensa la contención. Usa la sintaxis principal para el 90% de lo que escribes. Recurre a tablas, notas al pie y HTML solo cuando el documento realmente los necesite. Si te atienes a CommonMark o GFM, tus archivos se moverán entre editores, plataformas y convertidores sin sorpresas.
