Sintaxis de imagen Markdown 2026: GitHub, Notion, HackMD, Obsidian
Para quien tiene prisa: el resumen
- Sintaxis básica:
— funciona en todas las plataformas. - El cambio de tamaño es distinto en cada plataforma. Ahí viene el problema.
- La imagen debe estar en un enlace público directo. Los enlaces de Google Drive no funcionan.
Ahora, la tabla completa.
Sintaxis básica universal
texto alternativo: aparece si la imagen no carga; lo lee el lector de pantalla.URL-imagen: debe ser un enlace directo al archivo.
Con título (tooltip al pasar el ratón):
Sintaxis referenciada (útil si repites la imagen):
![texto alternativo][logo]
[logo]: https://example.com/image.png "Título"
Cómo se cambia el tamaño en cada plataforma
Aquí es donde la gente tropieza. Probé cinco plataformas populares y cada una lo hace a su manera.
| Plataforma | Sintaxis para tamaño | Ejemplo |
|---|---|---|
| GitHub | No acepta Markdown, usa HTML | <img src="url" width="300"> |
| HackMD | =anchoxalto tras la URL |
 |
| Notion | Solo arrastrando con el ratón | Sube y ajusta visualmente |
| Obsidian | ` | anchoo |
| Typora | HTML o zoom | <img src="url" style="zoom:50%"> |
GitHub
El renderizador Markdown de GitHub no acepta ninguna sintaxis para tamaño de imagen. Única vía: HTML.
<img src="https://example.com/image.png" width="400" alt="Descripción">
GitHub soporta los atributos width, height y align de <img>, pero filtra style por seguridad.
HackMD
HackMD usa una extensión propia, =anchoxalto después de la URL:
Solo ancho (alto en proporción):
Es exclusivo de HackMD, no funciona en ninguna otra plataforma.
Obsidian
La sintaxis de Obsidian va en el texto alternativo:
Obsidian también acepta enlaces internos estilo wiki:
![[image.png|300]]
Notion
Notion importa Markdown con sintaxis básica, pero el tamaño solo se ajusta con el ratón dentro de la interfaz. No hay opción por sintaxis.
Detalle importante: Notion re-sube las imágenes externas a su propio CDN (prod-files-secure.s3.us-west-2.amazonaws.com). Así que la fuente original no afecta a la velocidad de carga, pero tampoco puedes actualizar la imagen en Notion modificando el archivo original — tendrás que resubir manualmente.
Typora
Typora acepta HTML directamente, y además soporta style="zoom:50%", muy cómodo para previsualizaciones rápidas.
Compatibilidad de fuentes de imagen
No todas las URLs funcionan en todas las plataformas:
| Origen de imagen | GitHub | HackMD | Notion | Obsidian | Typora |
|---|---|---|---|---|---|
| Hosting directo (lpic.cc, ImgBB…) | OK | OK | OK | OK | OK |
| Imagen de repo GitHub | OK | OK | OK | Con config | OK |
| Enlace Google Drive | No | No | Re-subida automática | Inestable | No |
| Enlace Dropbox | No | No | Re-subida automática | Inestable | No |
| Base64 inline | OK | OK | No | OK | OK |
Resumen: los enlaces de Google Drive y Dropbox no son enlaces directos, la mayoría de plataformas Markdown no pueden renderizarlos. Para Markdown necesitas sí o sí un servicio que dé enlace directo.
Política de hotlinking: ¿bloquean tu imagen?
Hotlinking es incrustar en tu web una imagen alojada en el servidor de otro. Algunos servicios lo bloquean para ahorrar ancho de banda.
| Servicio | ¿Permite hotlinking? | Nota |
|---|---|---|
| Servicios de image hosting (lpic.cc, ImgBB…) | Sí | Es su función principal |
| Repo GitHub | Sí (con límites) | Tráfico alto puede sufrir throttling |
| Imgur | Parcial | Bloqueado desde ciertas regiones (TW desde 2025) |
| WordPress.com | No | Revisa Referer |
| Mayoría de webs comunes | No | Bloquean referencias externas |
Buenas prácticas para escritura técnica
Si escribes documentación o blogs técnicos, estas reglas te ahorran dolores:
No escatimes en texto alternativo
<!-- Mal -->
<!-- Bien -->
Función del alt:
- Texto visible si la imagen no carga.
- Lo lee el lector de pantalla (accesibilidad, WCAG).
- Google lo usa para entender el contenido de la imagen (SEO).
Nombres de archivo coherentes
<!-- Mal -->
Captura 2026-03-15 a las 14.32.05.png
IMG_4521.jpg
<!-- Bien -->
github-actions-workflow-config.png
npm-install-exito-salida.png
Dentro de seis meses, agradecerás poder identificar la imagen por el nombre.
Elección de formato
- Capturas y UI: PNG (texto nítido).
- Fotos y gráficos complejos: WebP o JPEG (pesan menos).
- Iconos, logos, diagramas: SVG (escala sin pérdida).
- Flujos o demos animadas: GIF o WebP animado (máximo 5 MB).
Comprime antes de subir
Independientemente del formato, comprime. Herramientas recomendadas:
- Squoosh (squoosh.app) — de Google, funciona en navegador.
- TinyPNG (tinypng.com) — compresión masiva PNG/JPEG.
- ImageOptim (macOS) — arrastra y comprime sin pérdida.
- Caesium (Windows/macOS, gratis, open source) — control fino y lotes.
Fórmula universal para máxima compatibilidad
Si necesitas que tu Markdown se vea bien en varias plataformas:
- Sintaxis: usa solo
estándar. Nada exclusivo de plataforma. - Tamaño: redimensiona antes de subir (ancho recomendado 600–800 px). No uses sintaxis de tamaño.
- Origen: usa un servicio que dé enlace directo — por ejemplo lpic.cc (sin registro, enlace directo inmediato). Evita Google Drive y Dropbox.
- Formato: PNG o WebP. Ignora BMP y TIFF, no son compatibles universalmente.
Aviso honesto: lpic.cc no hace redimensionado ni recorte on-the-fly. Si necesitas procesar imágenes sobre la marcha vía API (diferentes tamaños para cada ubicación en el artículo), Cloudinary o imgix encajan mejor para flujos automatizados. Para escritura técnica manual, lpic.cc cumple perfectamente.
Casos prácticos para escritores hispanohablantes
Algunos escenarios típicos donde estas reglas marcan diferencia:
Escribiendo documentación open source: si tu proyecto está en GitHub, mete las imágenes dentro del repo en docs/images/ o similar. Así quedan versionadas con el código. Para README público, usa HTML <img> para controlar tamaño.
Blog técnico en Hugo, Astro o Next.js: guarda las imágenes en static/ o public/ del proyecto y referencia con rutas relativas. Tu generador estático las sirve con buen caché.
Apuntes personales en Obsidian: con imágenes locales en una carpeta dedicada, sintaxis ![[imagen.png|400]] te da control rápido de tamaño.
Escribiendo en HackMD para presentar en reuniones: la sintaxis =500x te permite ajustar tamaño sin salir del editor. Muy útil para slides rápidas.
Colaboración en Notion con equipo LatAm: arrastra y suelta. Punto. Notion re-sube todo, no te compliques.
Preguntas frecuentes
¿Se pueden centrar imágenes en Markdown?
La sintaxis estándar no lo permite. En GitHub puedes usar <p align="center"><img src="url" width="400"></p>. HackMD soporta {:center}. Notion y Obsidian lo ajustan por interfaz, sin sintaxis.
¿Puedo usar imágenes locales en Markdown?
Sí, con ruta relativa: . Funciona en editores locales (Typora, Obsidian, VS Code). Pero si publicas el archivo online, necesitas subir las imágenes a un servicio y poner URLs públicas.
¿Por qué mi imagen no aparece en el README de GitHub?
Tres motivos habituales: (1) la URL no es directa — requiere login; (2) el servidor de origen bloquea hotlinking hacia GitHub; (3) la ruta relativa está mal, no corresponde a la estructura real del repo.
¿La sintaxis =300x de HackMD sirve en otras plataformas?
No. Es una extensión exclusiva de HackMD. GitHub, Notion, Obsidian, etc., la ignoran. Si el archivo va a viajar entre plataformas, ajusta tamaño antes de subir o usa HTML <img> (lo aceptan GitHub y HackMD).
¿Qué diferencia hay entre "enlace directo" y "enlace para compartir"?
El enlace directo apunta al archivo de imagen — típicamente acaba en .jpg, .png o .webp. El navegador abre solo la imagen. El enlace para compartir apunta a una página web que muestra la imagen entre otros elementos (típico de Google Drive). Markdown necesita enlace directo.
¿Qué servicio uso desde España para publicar en GitHub y Notion a la vez?
Cualquiera que dé enlace directo y CDN rápido sirve. Imgur tiene historial de borrar subidas anónimas (2023), así que si buscas algo sin riesgo: lpic.cc con expiración permanente, ImgBB con cuenta registrada, o Cloudinary para flujos más profesionales. Todos dan URL estable y carga rápida desde España y LatAm.
¿Cómo organizo las capturas de pantalla de documentación técnica?
Recomendación práctica: carpeta por proyecto, nombres descriptivos con prefijo de fecha (2026-03-15-github-actions.png), y formato PNG. Usa una herramienta de captura con anotación (Shottr en macOS, ShareX en Windows) para añadir flechas y etiquetas sin salir del flujo.