How to Embed GIFs in GitHub README

Quick Start

The fastest way to add an AgentGIF demo to your 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>

Replace YOUR_ID with your GIF's 8-character ID. This creates a centered, width-constrained GIF that links to the detail page.

1. Markdown Embed

Standard Markdown image syntax. Simple but left-aligned and unconstrained width:

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

Pros: Pure Markdown, works everywhere.
Cons: Left-aligned, full width on wide screens.

2. Centered HTML Embed (Recommended)

GitHub README files support a subset of HTML. Use this for centered GIFs with controlled width:

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

Why this works:

• align="center" — centers the block on GitHub
• width="800" — constrains maximum width (scales down on mobile)
• The <a> wrapper links to the AgentGIF detail page
• alt text describes the demo for accessibility and SEO

This is the format used by most open-source projects for README demos.

With a Caption

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

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

Note: GitHub strips <iframe> tags from README files. Use this method for documentation sites (Docusaurus, MkDocs, VitePress) and blog posts only.

4. Script Widget

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

Note: GitHub strips <script> tags. Use for your own website or documentation sites that allow scripts.

5. Badge Embed

Add a compact SVG badge to your badge row:

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

Combine with other 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

Paste an AgentGIF URL into platforms that support oEmbed (Notion, Slack, Discord). The platform auto-discovers the embed metadata and renders a rich preview.

Where to Place the Demo

The best position for a GIF demo in a README:

The most effective placement is near the top of the README, right after badges. First-time visitors decide within seconds whether to keep reading — a well-crafted GIF demo instantly communicates what your project does.

Sizing & Performance

Recommended Dimensions

File Size Guidelines

• Under 500 KB: Ideal — loads instantly
• 500 KB – 2 MB: Good — acceptable for most connections
• 2 – 5 MB: Use carefully — add loading="lazy"
• Over 5 MB: Consider splitting into shorter clips

GitHub Limitations

GitHub's Markdown renderer sanitizes HTML. Know what's allowed:

File size limit: GitHub serves images up to 10 MB from external URLs. AgentGIF GIFs are served from media.agentgif.com (Cloudflare R2 CDN), so there's no GitHub-side caching limit.

Best Practices

1. Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
2. Always link to the detail page — wrap the <img> in an <a> tag so viewers can see the full-size GIF and metadata
3. Keep it short — 5-15 second demos are most effective. Long recordings lose viewers.
4. Show the happy path — demonstrate the tool working, not error handling
5. Use a dark theme — dark terminal themes look better on GitHub's white and dark backgrounds
6. Version your tape file — commit the .tape file alongside the README so you can re-record when commands change