How to Embed GIFs in GitHub README

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

快速开始

将 AgentGIF 演示添加到 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>

将 YOUR_ID 替换为你 GIF 的 8 位 ID。这会创建一个居中、限宽的 GIF，并链接到详情页。

1. Markdown 嵌入

标准 Markdown 图片语法。简单但左对齐且宽度不受限：

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

优点： 纯 Markdown，到处适用。
缺点： 左对齐，在宽屏上占满全宽。

2. 居中 HTML 嵌入（推荐）

GitHub README 文件支持部分 HTML。使用此方式可实现居中且宽度可控的 GIF：

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

原理说明：

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
<a> 包裹层链接到 AgentGIF 详情页
alt 文本为无障碍访问和 SEO 描述演示内容

这是大多数开源项目在 README 演示中使用的格式。

带标题说明

<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 嵌入

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

注意：GitHub 会从 README 文件中移除 <iframe> 标签。此方法仅适用于文档站点（Docusaurus、MkDocs、VitePress）和博客文章。

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

注意：GitHub 会移除 <script> 标签。仅适用于你自己的网站或允许脚本的文档站点。

5. 徽章嵌入

将紧凑型 SVG 徽章添加到你的徽章行中：

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

与其他徽章组合使用：

[![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

将 AgentGIF URL 粘贴到支持 oEmbed 的平台（Notion、Slack、Discord）。平台会自动发现嵌入元数据并渲染富媒体预览。

演示的最佳位置

GIF 演示在 README 中的最佳位置：

位置	最佳用途
徽章之后、描述之前	库和 CLI 工具——即时视觉冲击
After "Features" section	复杂工具——展示功能实战
In "Quick Start" section	教程——展示预期输出
在每个功能小节中	功能丰富的项目——每个功能一个 GIF

最有效的位置是 README 顶部附近，紧接徽章之后。首次访问者会在几秒内决定是否继续阅读——精心制作的 GIF 演示能立即传达你的项目功能。

尺寸与性能

文件大小指南

500 KB 以下：理想——瞬间加载
500 KB – 2 MB：良好——大多数网络连接可接受
2 – 5 MB: Use carefully — add loading="lazy"
超过 5 MB：考虑拆分为更短的片段

GitHub 限制

GitHub 的 Markdown 渲染器会过滤 HTML。了解哪些是允许的：

允许	被移除
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, 事件处理器
`<details>`/`<summary>` (可折叠)	`<form>`, `<input>`

文件大小限制：GitHub 从外部 URL 提供最大 10 MB 的图片。AgentGIF 的 GIF 从 media.agentgif.com（Cloudflare R2 CDN）提供，因此没有 GitHub 端的缓存限制。

最佳实践

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
始终链接到详情页——将 <img> 包裹在 <a> 标签中，让观看者可以查看完整尺寸的 GIF 和元数据
保持简短——5-15 秒的演示最为有效。录制过长会流失观看者。
展示正常流程——演示工具正常工作的过程，而非错误处理
使用深色主题——深色终端主题在 GitHub 的白色和深色背景上都更好看
对 tape 文件进行版本管理——将 .tape 文件与 README 一起提交，以便命令变更时重新录制

← 所有指南 · asciinema 对比 AgentGIF →

场景	宽度	备注
GitHub README	`width="800"`	适合内容栏宽度，无需滚动
文档站点	`width="100%"` 配合 `max-width: 800px`	响应式
博客文章	`width="700"`	标准文章宽度