How to Embed GIFs in GitHub README

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

Início Rápido

A maneira mais rápida de adicionar uma demo do AgentGIF ao seu 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>

Substitua YOUR_ID pelo ID de 8 caracteres do seu GIF. Isso cria um GIF centralizado com largura limitada que linka para a página de detalhe.

1. Embed Markdown

Sintaxe padrão de imagem Markdown. Simples, mas alinhado à esquerda e com largura ilimitada:

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

Prós: Markdown puro, funciona em todos os lugares.
Contras: Alinhado à esquerda, largura total em telas largas.

2. Embed HTML Centralizado (Recomendado)

Os arquivos GitHub README suportam um subconjunto de HTML. Use isso para GIFs centralizados com largura controlada:

<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 que isso funciona:

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
O wrapper <a> linka para a página de detalhe do AgentGIF
O texto alt descreve a demo para acessibilidade e SEO

Este é o formato usado pela maioria dos projetos de código aberto para demos em README.

Com Legenda

<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. Embed iframe

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

Nota: O GitHub remove tags <iframe> dos arquivos README. Use este método apenas para sites de documentação (Docusaurus, MkDocs, VitePress) e posts de blog.

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

Nota: O GitHub remove tags <script>. Use para seu próprio site ou sites de documentação que permitem scripts.

5. Embed de Badge

Adicione um badge SVG compacto à sua linha de badges:

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

Combine com outros 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

Cole uma URL do AgentGIF em plataformas que suportam oEmbed (Notion, Slack, Discord). A plataforma descobre automaticamente os metadados de embed e renderiza uma pré-visualização rica.

Onde Colocar a Demo

A melhor posição para uma demo em GIF em um README:

Posição	Melhor Para
Depois dos badges, antes da descrição	Bibliotecas e ferramentas CLI — impacto visual imediato
After "Features" section	Ferramentas complexas — mostre os recursos em ação
In "Quick Start" section	Tutoriais — mostre a saída esperada
Em cada subseção de recurso	Projetos ricos em recursos — um GIF por recurso

O posicionamento mais eficaz é perto do topo do README, logo após os badges. Visitantes pela primeira vez decidem em segundos se continuam a leitura — uma demo em GIF bem elaborada comunica instantaneamente o que seu projeto faz.

Dimensionamento e Desempenho

Dimensões Recomendadas

Contexto	Largura	Notas
GitHub README	`width="800"`	Cabe na coluna de conteúdo sem rolagem
Site de documentação	`width="100%"` com `max-width: 800px`	Responsivo
Post de blog	`width="700"`	Largura padrão de artigo

Diretrizes de Tamanho de Arquivo

Abaixo de 500 KB: Ideal — carrega instantaneamente
500 KB – 2 MB: Bom — aceitável para a maioria das conexões
2 – 5 MB: Use carefully — add loading="lazy"
Acima de 5 MB: Considere dividir em clipes mais curtos

Limitações do GitHub

O renderizador Markdown do GitHub sanitiza HTML. Saiba o que é permitido:

Permitido	Removido
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, manipuladores de eventos
`<details>`/`<summary>` (recolhível)	`<form>`, `<input>`

Limite de tamanho de arquivo: O GitHub serve imagens de até 10 MB de URLs externas. Os GIFs do AgentGIF são servidos de media.agentgif.com (Cloudflare R2 CDN), então não há limite de cache do lado do GitHub.

Melhores Práticas

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Sempre crie link para a página de detalhe — envolva o <img> em uma tag <a> para que os visitantes possam ver o GIF em tamanho completo e os metadados
Mantenha curto — demos de 5-15 segundos são mais eficazes. Gravações longas perdem espectadores.
Mostre o caminho feliz — demonstre a ferramenta funcionando, não o tratamento de erros
Use um tema escuro — temas de terminal escuros ficam melhores nos fundos branco e escuro do GitHub
Versione seu arquivo tape — faça commit do arquivo .tape junto com o README para que você possa regravar quando os comandos mudarem

← Todos os Guias · asciinema vs AgentGIF →