How to Embed GIFs in GitHub README

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

Mulai Cepat

Cara tercepat untuk menambahkan demo AgentGIF ke README Anda:

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

Ganti YOUR_ID dengan ID GIF 8 karakter Anda. Ini membuat GIF terpusat dengan lebar terbatas yang tertaut ke halaman detail.

1. Embed Markdown

Sintaks gambar Markdown standar. Sederhana tetapi rata kiri dan lebar tidak terbatas:

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

Kelebihan: Markdown murni, berfungsi di mana saja.
Kekurangan: Rata kiri, lebar penuh di layar lebar.

2. Embed HTML Terpusat (Direkomendasikan)

File GitHub README mendukung subset HTML. Gunakan ini untuk GIF terpusat dengan lebar terkontrol:

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

Mengapa ini berhasil:

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
Wrapper <a> menautkan ke halaman detail AgentGIF
Teks alt mendeskripsikan demo untuk aksesibilitas dan SEO

Ini adalah format yang digunakan oleh sebagian besar proyek open-source untuk demo README.

Dengan Keterangan

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

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

Catatan: GitHub menghapus tag <iframe> dari file README. Gunakan metode ini hanya untuk situs dokumentasi (Docusaurus, MkDocs, VitePress) dan posting blog.

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

Catatan: GitHub menghapus tag <script>. Gunakan untuk situs web Anda sendiri atau situs dokumentasi yang mengizinkan skrip.

5. Embed Badge

Tambahkan badge SVG kompak ke baris badge Anda:

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

Gabungkan dengan badge lain:

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

Tempelkan URL AgentGIF ke platform yang mendukung oEmbed (Notion, Slack, Discord). Platform secara otomatis menemukan metadata embed dan merender pratinjau kaya.

Di Mana Menempatkan Demo

Posisi terbaik untuk demo GIF dalam README:

Posisi	Terbaik Untuk
Setelah badge, sebelum deskripsi	Perpustakaan dan alat CLI — dampak visual langsung
After "Features" section	Alat kompleks — tampilkan fitur beraksi
In "Quick Start" section	Tutorial — tampilkan output yang diharapkan
Di setiap subbagian fitur	Proyek kaya fitur — satu GIF per fitur

Penempatan paling efektif adalah di dekat bagian atas README, tepat setelah badge. Pengunjung pertama kali memutuskan dalam hitungan detik apakah akan terus membaca — demo GIF yang dibuat dengan baik segera mengkomunikasikan apa yang dilakukan proyek Anda.

Ukuran & Performa

Dimensi yang Direkomendasikan

Konteks	Lebar	Catatan
GitHub README	`width="800"`	Sesuai dengan kolom konten tanpa scroll
Situs dokumentasi	`width="100%"` dengan `max-width: 800px`	Responsif
Posting blog	`width="700"`	Lebar artikel standar

Panduan Ukuran File

Di bawah 500 KB: Ideal — dimuat seketika
500 KB – 2 MB: Baik — dapat diterima untuk sebagian besar koneksi
2 – 5 MB: Use carefully — add loading="lazy"
Di atas 5 MB: Pertimbangkan untuk membagi menjadi klip yang lebih pendek

Keterbatasan GitHub

Renderer Markdown GitHub membersihkan HTML. Ketahui apa yang diizinkan:

Diizinkan	Dihapus
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, penangan event
`<details>`/`<summary>` (dapat dilipat)	`<form>`, `<input>`

Batas ukuran file: GitHub menyajikan gambar hingga 10 MB dari URL eksternal. GIF AgentGIF disajikan dari media.agentgif.com (CDN Cloudflare R2), sehingga tidak ada batas cache dari sisi GitHub.

Praktik Terbaik

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Selalu tautkan ke halaman detail — bungkus <img> dalam tag <a> agar penonton dapat melihat GIF ukuran penuh dan metadata
Singkat saja — demo 5-15 detik paling efektif. Rekaman panjang kehilangan penonton.
Tampilkan jalur bahagia — demonstrasikan alat yang berfungsi, bukan penanganan error
Gunakan tema gelap — tema terminal gelap terlihat lebih baik di latar belakang putih dan gelap GitHub
Versi file tape Anda — commit file .tape bersama README sehingga Anda dapat merekam ulang ketika perintah berubah

← Semua Panduan · asciinema vs AgentGIF →