Embed Guide

URL Structure

Every GIF has three URLs you'll reference when embedding:

Replace {ID} with the 8-character GIF ID (e.g., xK9mQ2pL).

1. Markdown

The most common format for GitHub README files. Wraps the GIF image in a link to the detail page:

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

With centered alignment (GitHub-flavored HTML in Markdown):

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

2. HTML <img>

Use the raw GIF URL in an <img> tag for full control over sizing and styling:

<a href="https://agentgif.com/ID">
  <img src="https://media.agentgif.com/ID.gif"
       alt="Terminal demo"
       width="800"
       loading="lazy">
</a>

The loading="lazy" attribute defers loading until the image is near the viewport — useful for pages with multiple GIFs.

3. iframe (Interactive Player)

The iframe embed includes the interactive terminal player with theme switching, playback controls, and cast replay:

<iframe
  src="https://agentgif.com/embed/ID/"
  width="800"
  height="500"
  frameborder="0"
  allow="clipboard-write"
  loading="lazy"
></iframe>

The player auto-detects dark/light mode from the parent page. You can force a theme with a query parameter:

https://agentgif.com/embed/ID/?theme=dracula

4. Script Widget (Auto-embed)

Drop a single div and script tag — the widget handles everything automatically:

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

The widget renders a responsive player that adapts to the container width. Multiple embeds on one page share the same script — only include it once.

5. oEmbed

AgentGIF supports oEmbed for auto-discovery. Platforms like Notion, Slack, Discord, and WordPress can automatically render a rich preview when you paste an AgentGIF URL.

The HTML <link> tag on each GIF page enables auto-discovery:

<link rel="alternate" type="application/json+oembed"
  href="https://agentgif.com/oembed?url=https://agentgif.com/ID&format=json" />

Query the oEmbed endpoint directly:

curl "https://agentgif.com/api/v1/oembed/?url=https://agentgif.com/ID&format=json"

Response:

{
  "type": "photo",
  "version": "1.0",
  "title": "Docker Compose Up",
  "width": 1000,
  "height": 580,
  "url": "https://media.agentgif.com/ID.gif",
  "provider_name": "AgentGIF",
  "provider_url": "https://agentgif.com"
}

6. Badge (SVG)

A compact SVG badge linking to the GIF. Useful in badge rows of README files:

<a href="https://agentgif.com/ID">
  <img src="https://agentgif.com/badge/ID.svg" alt="AgentGIF demo">
</a>

In Markdown:

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

Platform-Specific Tips

GitHub README

GitHub renders both Markdown and HTML in README files. Use the centered HTML pattern for best results — it centers the GIF and constrains the width:

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

GitHub strips <iframe> and <script> tags — use the Markdown or HTML <img> method only.

See the full guide: How to Embed GIFs in GitHub README.

Notion

Paste an AgentGIF URL directly into a Notion page. Notion's oEmbed support will auto-render a preview. Alternatively, use the /embed block and paste the embed URL.

Slack & Discord

Paste the GIF detail URL (https://agentgif.com/ID). Both platforms support oEmbed unfurling and will show a rich preview with the GIF image.

Documentation Sites (Docusaurus, MkDocs, VitePress)

Use the Markdown or HTML embed. Most documentation generators support standard HTML in Markdown files. The iframe embed works if your generator doesn't strip iframes.

Responsive Sizing

For responsive embeds that scale to the container width:

<div style="max-width: 800px; margin: 0 auto;">
  <a href="https://agentgif.com/ID">
    <img src="https://media.agentgif.com/ID.gif"
         alt="demo"
         style="width: 100%; height: auto;">
  </a>
</div>

For responsive iframes, wrap in a container with aspect ratio:

<div style="position: relative; padding-bottom: 58%; max-width: 800px;">
  <iframe src="https://agentgif.com/embed/ID/"
          style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
          frameborder="0"></iframe>
</div>