How to Embed GIFs in GitHub README

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

Hızlı Başlangıç

README'nize bir AgentGIF demosu eklemenin en hızlı yolu:

<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 yerine GIF'inizin 8 karakterli kimliğini yazın. Bu, detay sayfasına bağlanan ortalanmış, genişliği sınırlanmış bir GIF oluşturur.

1. Markdown Gömme

Standart Markdown görüntü söz dizimi. Basit ama sola hizalı ve genişlik kısıtlaması olmadan:

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

Artıları: Saf Markdown, her yerde çalışır.
Eksileri: Sola hizalı, geniş ekranlarda tam genişlik.

2. Ortalanmış HTML Gömme (Önerilen)

GitHub README dosyaları bir HTML alt kümesini destekler. Kontrollü genişlikte ortalanmış GIF'ler için bunu kullanın:

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

Bunun işe yarama nedeni:

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
<a> sarmalayıcısı AgentGIF detay sayfasına bağlanır
alt metni, erişilebilirlik ve SEO için demoyu açıklar

Bu, çoğu açık kaynak projesinin README demoları için kullandığı formattır.

Alt Yazı ile

<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 Gömme

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

Not: GitHub, README dosyalarından <iframe> etiketlerini kaldırır. Bu yöntemi yalnızca dokümantasyon siteleri (Docusaurus, MkDocs, VitePress) ve blog yazıları için kullanın.

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

Not: GitHub, <script> etiketlerini kaldırır. Kendi web siteniz veya betiklere izin veren dokümantasyon siteleri için kullanın.

5. Rozet Gömme

Rozet satırınıza kompakt bir SVG rozet ekleyin:

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

Diğer rozetlerle birleştirin:

[![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 destekleyen platformlara (Notion, Slack, Discord) bir AgentGIF URL'si yapıştırın. Platform, gömme meta verilerini otomatik olarak keşfeder ve zengin bir önizleme oluşturur.

Demoyu Nereye Yerleştirmeli

README'de bir GIF demosu için en iyi konum:

Konum	En İyi Kullanım
Rozetlerden sonra, açıklamadan önce	Kütüphaneler ve CLI araçları — anında görsel etki
After "Features" section	Karmaşık araçlar — özellikleri çalışırken gösterin
In "Quick Start" section	Eğitimler — beklenen çıktıyı gösterin
Her özellik alt bölümünde	Özellik açısından zengin projeler — her özellik için bir GIF

En etkili yerleşim, rozetlerin hemen ardından README'nin üst kısmına yakındır. İlk kez gelen ziyaretçiler okumaya devam edip etmeyeceklerine saniyeler içinde karar verir — iyi hazırlanmış bir GIF demosu projenizin ne yaptığını anında iletir.

Boyutlandırma ve Performans

Önerilen Boyutlar

Bağlam	Genişlik	Notlar
GitHub README	`width="800"`	Kaydırma olmadan içerik sütununa sığar
Dokümantasyon sitesi	`width="100%"` ile `max-width: 800px`	Duyarlı
Blog yazısı	`width="700"`	Standart makale genişliği

Dosya Boyutu Kılavuzları

500 KB altı: İdeal — anında yüklenir
500 KB – 2 MB: İyi — çoğu bağlantı için kabul edilebilir
2 – 5 MB: Use carefully — add loading="lazy"
5 MB üzeri: Daha kısa kliplere bölmeyi düşünün

GitHub Sınırlamaları

GitHub'ın Markdown oluşturucusu HTML'i temizler. Neye izin verildiğini bilin:

İzin Verilen	Kaldırılan
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, olay işleyicileri
`<details>`/`<summary>` (katlanabilir)	`<form>`, `<input>`

Dosya boyutu sınırı: GitHub, harici URL'lerden 10 MB'a kadar görüntü sunar. AgentGIF GIF'leri media.agentgif.com (Cloudflare R2 CDN) üzerinden sunulur, bu nedenle GitHub tarafında önbellek sınırı yoktur.

En İyi Uygulamalar

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Her zaman detay sayfasına bağlantı verin — izleyicilerin tam boyutlu GIF'i ve meta verileri görebilmesi için <img> etiketini bir <a> etiketine sarın
Kısa tutun — 5-15 saniyelik demolar en etkilidir. Uzun kayıtlar izleyicileri kaybeder.
Başarılı senaryoyu gösterin — hata yönetimini değil, aracın çalışmasını gösterin
Koyu tema kullanın — koyu terminal temaları GitHub'ın beyaz ve koyu arka planlarında daha iyi görünür
Tape dosyanızı sürümleyin — komutlar değiştiğinde yeniden kaydetmeniz için .tape dosyasını README ile birlikte commitleyin

← Tüm Kılavuzlar · asciinema vs AgentGIF →