Imágenes en Markdown: insertar, redimensionar y enlazar
Cómo insertar imágenes en Markdown con la sintaxis de exclamación, poner texto alternativo, hacerlas clicables, controlar el tamaño con HTML y usar rutas relativas o absolutas.
Insertar una imagen en Markdown es casi idéntico a poner un enlace. La única diferencia es un signo de exclamación al principio.
Sintaxis básica
Las tres partes:
!— indica que es una imagen y no un enlace.[Texto alternativo]— lo que se muestra si la imagen no carga, y lo que leen los lectores de pantalla.(/ruta)— la ubicación del archivo, relativa o absoluta.
El texto alternativo no es opcional
Técnicamente puedes dejar los corchetes vacíos y la imagen se verá igual. Pero el texto alternativo genera el atributo alt del HTML, y ese atributo cumple tres funciones reales:
- Accesibilidad. Es lo único que percibe alguien que navega con lector de pantalla.
- Tolerancia a fallos. Si la imagen no carga —enlace roto, red lenta, bloqueador—, es lo que ve el usuario.
- SEO. Es la principal señal que tiene Google para entender de qué es la imagen.
Escribe una descripción real de lo que se ve:
❌ 
❌ 
❌ 
✅ Excepción: si la imagen es puramente decorativa y no aporta información, el alt vacío es lo correcto —le dice al lector de pantalla que la ignore en lugar de leer un nombre de archivo sin sentido.
Título emergente
Igual que en los enlaces, puedes añadir un título entre comillas. Aparece al pasar el cursor por encima:
Es opcional y no sustituye al alt: el título es un extra, el alt es el mínimo.
Imágenes de referencia
Si repites la misma imagen o las URLs son largas, aplica el mismo sistema de referencias que los enlaces:
Aquí va el logo: ![Logo de Markdown][logo]
Y aquí otra vez: ![Logo de Markdown][logo]
[logo]: /markdown-logo.png "Logotipo oficial"La definición desaparece del resultado final y mantiene el texto limpio.
Imágenes clicables
Envuelve la imagen en la sintaxis de enlace. La imagen va dentro de los corchetes:
[](https://markdown.es)Es el patrón de las insignias de estado en los README de GitHub: la insignia es una imagen y al pulsarla te lleva al panel de la herramienta correspondiente.
Rutas: relativas o absolutas
En un repositorio de GitHub conviene usar rutas relativas: siguen funcionando aunque el repositorio se renombre, se clone o se mueva de organización. Enlazar a https://github.com/usuario/repo/blob/main/... es frágil.
⚠️ Si usas rutas relativas en GitHub, apunta a raw.githubusercontent.com o usa la ruta del archivo directamente; un enlace a la página de vista previa de GitHub devuelve HTML, no la imagen.
Controlar el tamaño
Markdown no tiene sintaxis para el tamaño de una imagen. Es una de sus limitaciones más conocidas. Las opciones:
HTML en línea (universal)
<img src="/foto.jpg" alt="Descripción" width="400">Funciona en cualquier procesador que admita HTML, que son casi todos. Si indicas solo width, la altura se ajusta proporcionalmente.
Sintaxis extendida (según plataforma)
Algunos procesadores han inventado la suya. No son portables:
 <!-- Typora, algunos -->
 <!-- Obsidian -->CSS (la vía limpia)
Si controlas el sitio, lo mejor es dejar Markdown en paz y limitar el tamaño desde la hoja de estilos:
article img { max-width: 100%; height: auto; }Es lo que hace esta web: las imágenes se insertan con sintaxis Markdown normal y el CSS se encarga de que nunca desborden.
Lo que Markdown tampoco hace
Alinear o flotar la imagen. No hay sintaxis. Requiere HTML con style o una clase CSS.
Pies de foto. No existen de forma nativa. Lo habitual es poner un párrafo en cursiva justo debajo, o usar HTML con <figure> y <figcaption>, que es lo semánticamente correcto:
<figure>
<img src="/grafico.png" alt="Evolución de usuarios">
<figcaption>Usuarios mensuales entre 2020 y 2025</figcaption>
</figure>Galerías o carruseles. Fuera del alcance del lenguaje por completo.
Imágenes responsive con srcset. Solo con HTML.
Formatos y peso
Markdown no impone ningún formato: si el navegador lo muestra, funciona. Un par de recomendaciones prácticas:
- WebP o AVIF para fotografías: pesan bastante menos que JPEG con calidad equivalente.
- SVG para logos, iconos y diagramas: escala sin perder nitidez y suele pesar muy poco.
- PNG solo cuando necesites transparencia y el SVG no valga.
El peso de las imágenes es, en la mayoría de sitios, el principal responsable de una carga lenta. Merece más atención de la que suele recibir.
Errores frecuentes
Olvidar la exclamación. Sin el ! tienes un enlace de texto, no una imagen. Es el fallo número uno.
Espacio entre corchete y paréntesis. ![alt] (/ruta) no funciona. Deben ir pegados.
Ruta incorrecta. Si ves el texto alternativo en lugar de la imagen, la ruta está mal. Ahí se nota el valor de tener un alt descriptivo: te dice qué imagen falta.
Espacios en el nombre del archivo. Sustitúyelos por guiones o codifícalos como %20. Renombrar el archivo es siempre mejor idea.
Compatibilidad
La sintaxis básica funciona en todas partes. El dimensionado con HTML funciona donde se admite HTML en línea, que es casi todo excepto algunos procesadores restringidos por seguridad (ciertos comentarios de plataformas, correo). Las sintaxis extendidas de tamaño son específicas de cada editor.
Pruébalo
Comprueba que tus rutas resuelven bien en el previsualizador de Markdown. Y si estás migrando contenido desde una web, el conversor de HTML a Markdown transforma las etiquetas <img> conservando el alt.