How to Embed GIFs in GitHub README

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

クイックスタート

README に AgentGIF デモを追加する最速の方法:

<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

oEmbed をサポートするプラットフォーム (Notion、Slack、Discord) に AgentGIF URL をペーストします。プラットフォームが埋め込みメタデータを自動発見し、リッチプレビューをレンダリングします。

デモの配置場所

README での GIF デモの最適な配置:

位置	最適な用途
バッジの後、説明の前	ライブラリと CLI ツール — 即座のビジュアルインパクト
After "Features" section	複雑なツール — 機能を動作中に表示
In "Quick Start" section	チュートリアル — 期待される出力を表示
各機能サブセクション内	機能豊富なプロジェクト — 機能ごとに 1 つの GIF

最も効果的な配置は、バッジのすぐ後の README の上部付近 です。初回訪問者は数秒以内に読み続けるかどうかを決めます — よく作られた GIF デモはプロジェクトが何をするかを瞬時に伝えます。

サイズとパフォーマンス

推奨サイズ

コンテキスト	幅	注記
GitHub README	`width="800"`	スクロールなしでコンテンツカラムに収まる
ドキュメントサイト	`width="100%"` 付き `max-width: 800px`	レスポンシブ
ブログ記事	`width="700"`	標準記事幅

ファイルサイズガイドライン

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"
常に詳細ページにリンク — 視聴者がフルサイズの GIF とメタデータを見られるように <img> を <a> タグで囲む
短くする — 5～15 秒のデモが最も効果的。長い録画は視聴者を失います。
ハッピーパスを見せる — エラー処理ではなく、ツールの動作をデモ
ダークテーマを使用 — ダークターミナルテーマは GitHub の白とダークの背景でより見栄えがします
テープファイルをバージョン管理 — コマンドが変更されたときに再録画できるように .tape ファイルを README と一緒にコミット

← すべてのガイド · asciinema vs AgentGIF →