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 8-символьным ID вашего GIF. Это создаёт центрированный 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 удаляет теги <iframe> из файлов README. Используйте этот метод только для сайтов документации (Docusaurus, MkDocs, VitePress) и блогов.

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

Примечание: GitHub удаляет теги <script>. Используйте для собственного сайта или сайтов документации, разрешающих скрипты.

5. Встраивание Badge

Добавьте компактный 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

Вставьте URL AgentGIF на платформы, поддерживающие oEmbed (Notion, Slack, Discord). Платформа автоматически обнаружит метаданные встраивания и отобразит расширенный предпросмотр.

Где разместить демо

Лучшее расположение демо-GIF в README:

Позиция	Лучше всего для
После бейджей, перед описанием	Библиотеки и CLI-инструменты — немедленное визуальное воздействие
After "Features" section	Сложные инструменты — показывайте функции в действии
In "Quick Start" section	Обучающие материалы — показывайте ожидаемый вывод
В каждом подразделе функций	Функционально насыщенные проекты — один GIF на функцию

Наиболее эффективное расположение — ближе к верху README, сразу после бейджей. Новые посетители решают за считанные секунды, продолжать ли чтение — хорошо сделанное GIF-демо мгновенно передаёт суть вашего проекта.

Размеры и производительность

Ограничения GitHub

Рендерер Markdown GitHub очищает HTML. Знайте, что разрешено:

Разрешено	Удаляется
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, обработчики событий
`<details>`/`<summary>` (сворачиваемое)	`<form>`, `<input>`

Ограничение размера файла: GitHub обслуживает изображения до 10 МБ с внешних URL. GIF AgentGIF обслуживаются с 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 секунд наиболее эффективны. Длинные записи теряют зрителей.
Показывайте happy path — демонстрируйте работающий инструмент, а не обработку ошибок
Используйте тёмную тему — тёмные терминальные темы лучше смотрятся на белом и тёмном фоне GitHub
Версионируйте файл tape — коммитьте файл .tape вместе с README, чтобы при изменении команд можно было перезаписать

← Все руководства · asciinema vs AgentGIF →

Контекст	Ширина	Примечания
GitHub README	`width="800"`	Вписывается в колонку контента без прокрутки
Сайт документации	`width="100%"` с `max-width: 800px`	Адаптивный
Пост в блоге	`width="700"`	Стандартная ширина статьи