How to Embed GIFs in GitHub README

Complete guide to embedding animated GIFs in GitHub README files with Markdown, HTML, and iframe embeds.

Inicio rápido

La forma más rápida de añadir una demostración de AgentGIF a tu README:

<p align="center">
  <a href="https://agentgif.com/YOUR_ID">
    <img src="https://media.agentgif.com/YOUR_ID.gif" alt="demo" width="800">
  </a>
</p>

Reemplaza YOUR_ID con el ID de 8 caracteres de tu GIF. Esto crea un GIF centrado con ancho limitado que enlaza a la página de detalle.

1. Incrustación Markdown

Sintaxis estándar de imagen Markdown. Simple pero alineada a la izquierda y sin límite de ancho:

[![Demo](https://media.agentgif.com/ID.gif)](https://agentgif.com/ID)

Pros: Markdown puro, funciona en cualquier parte.
Contras: Alineado a la izquierda, ancho completo en pantallas anchas.

2. Incrustación HTML centrada (recomendada)

Los archivos README de GitHub admiten un subconjunto de HTML. Usa esto para GIFs centrados con ancho controlado:

<p align="center">
  <a href="https://agentgif.com/ID">
    <img src="https://media.agentgif.com/ID.gif" alt="project demo" width="800">
  </a>
</p>

Por qué funciona:

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
El envoltorio <a> enlaza a la página de detalle de AgentGIF
El texto alt describe la demostración para accesibilidad y SEO

Este es el formato que usan la mayoría de los proyectos de código abierto para las demostraciones en README.

Con pie de imagen

<p align="center">
  <a href="https://agentgif.com/ID">
    <img src="https://media.agentgif.com/ID.gif" alt="demo" width="800">
  </a>
  <br>
  <em>Recording with <a href="https://agentgif.com">AgentGIF</a></em>
</p>

3. Incrustación iframe

<iframe src="https://agentgif.com/embed/ID/" width="800" height="500" frameborder="0"></iframe>

Nota: GitHub elimina las etiquetas <iframe> de los archivos README. Usa este método solo para sitios de documentación (Docusaurus, MkDocs, VitePress) y publicaciones de blog.

<div data-agentgif="ID"></div>
<script src="https://agentgif.com/widget.js" async></script>

Nota: GitHub elimina las etiquetas <script>. Úsalo para tu propio sitio web o sitios de documentación que permitan scripts.

5. Incrustación de badge

Añade un badge SVG compacto a tu fila de badges:

[![AgentGIF demo](https://agentgif.com/badge/ID.svg)](https://agentgif.com/ID)

Combina con otros badges:

[![PyPI](https://img.shields.io/pypi/v/mypackage)](https://pypi.org/project/mypackage/)
[![AgentGIF demo](https://agentgif.com/badge/ID.svg)](https://agentgif.com/ID)

6. oEmbed

Pega una URL de AgentGIF en plataformas que admiten oEmbed (Notion, Slack, Discord). La plataforma descubre automáticamente los metadatos de incrustación y renderiza una vista previa enriquecida.

Dónde colocar la demostración

La mejor posición para una demostración GIF en un README:

Posición	Ideal para
Después de los badges, antes de la descripción	Bibliotecas y herramientas CLI — impacto visual inmediato
After "Features" section	Herramientas complejas — mostrar características en acción
In "Quick Start" section	Tutoriales — mostrar la salida esperada
En cada subsección de características	Proyectos con muchas características — un GIF por característica

La colocación más efectiva es cerca de la parte superior del README, justo después de los badges. Los visitantes por primera vez deciden en segundos si seguir leyendo — una demostración GIF bien elaborada comunica instantáneamente qué hace tu proyecto.

Tamaño y rendimiento

Dimensiones recomendadas

Contexto	Ancho	Notas
GitHub README	`width="800"`	Se ajusta a la columna de contenido sin desplazamiento
Sitio de documentación	`width="100%"` con `max-width: 800px`	Adaptable
Publicación de blog	`width="700"`	Ancho de artículo estándar

Directrices de tamaño de archivo

Menos de 500 KB: Ideal — carga instantáneamente
500 KB – 2 MB: Bueno — aceptable para la mayoría de conexiones
2 – 5 MB: Use carefully — add loading="lazy"
Más de 5 MB: Considera dividirlo en clips más cortos

Limitaciones de GitHub

El renderizador de Markdown de GitHub sanea el HTML. Conoce qué está permitido:

Permitido	Eliminado
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, manejadores de eventos
`<details>`/`<summary>` (colapsable)	`<form>`, `<input>`

Límite de tamaño de archivo: GitHub sirve imágenes de hasta 10 MB desde URLs externas. Los GIFs de AgentGIF se sirven desde media.agentgif.com (Cloudflare R2 CDN), por lo que no hay límite de caché del lado de GitHub.

Buenas prácticas

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Siempre enlaza a la página de detalle — envuelve <img> en una etiqueta <a> para que los espectadores puedan ver el GIF a tamaño completo y sus metadatos
Mantenlo corto — las demostraciones de 5-15 segundos son más efectivas. Las grabaciones largas pierden espectadores.
Muestra el camino feliz — demuestra la herramienta funcionando, no el manejo de errores
Usa un tema oscuro — los temas oscuros de terminal se ven mejor sobre los fondos blanco y oscuro de GitHub
Versiona tu archivo de cinta — haz commit del archivo .tape junto al README para poder volver a grabar cuando cambien los comandos

← Todas las guías · asciinema vs AgentGIF →