How to Embed GIFs in GitHub README

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

Schnellstart

Der schnellste Weg, eine AgentGIF-Demo zu Ihrem README hinzuzufügen:

<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 durch die 8-Zeichen-ID Ihres GIFs ersetzen. Dies erstellt ein zentriertes, breitenbeschränktes GIF, das auf die Detailseite verweist.

1. Markdown-Einbettung

Standard-Markdown-Bildsyntax. Einfach, aber linksbündig und ohne Breitenbeschränkung:

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

Vorteile: Reines Markdown, funktioniert überall.
Nachteile: Linksbündig, volle Breite auf breiten Bildschirmen.

2. Zentrierte HTML-Einbettung (Empfohlen)

GitHub README-Dateien unterstützen eine Teilmenge von HTML. Verwenden Sie dies für zentrierte GIFs mit kontrollierter Breite:

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

Warum das funktioniert:

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
Das <a>-Wrapper-Element verweist auf die AgentGIF-Detailseite
alt-Text beschreibt die Demo für Barrierefreiheit und SEO

Dies ist das Format, das die meisten Open-Source-Projekte für README-Demos verwenden.

Mit einer Bildunterschrift

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

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

Hinweis: GitHub entfernt <iframe>-Tags aus README-Dateien. Verwenden Sie diese Methode nur für Dokumentationswebsites (Docusaurus, MkDocs, VitePress) und Blogbeiträge.

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

Hinweis: GitHub entfernt <script>-Tags. Für Ihre eigene Website oder Dokumentationswebsites verwenden, die Scripts erlauben.

5. Badge-Einbettung

Fügen Sie Ihrer Badge-Zeile einen kompakten SVG-Badge hinzu:

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

Mit anderen Badges kombinieren:

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

Eine AgentGIF-URL in Plattformen einfügen, die oEmbed unterstützen (Notion, Slack, Discord). Die Plattform erkennt automatisch die Einbettungsmetadaten und rendert eine umfangreiche Vorschau.

Wo die Demo platzieren

Die beste Position für eine GIF-Demo in einem README:

Position	Am besten geeignet für
Nach Badges, vor der Beschreibung	Bibliotheken und CLI-Tools — sofortige visuelle Wirkung
After "Features" section	Komplexe Tools — Funktionen in Aktion zeigen
In "Quick Start" section	Tutorials — erwartete Ausgabe zeigen
In jedem Funktions-Unterabschnitt	Funktionsreiche Projekte — ein GIF pro Funktion

Die effektivste Platzierung ist nahe dem Anfang des README, direkt nach den Badges. Erstbesucher entscheiden innerhalb von Sekunden, ob sie weiterlesen — eine gut gestaltete GIF-Demo kommuniziert sofort, was Ihr Projekt tut.

Größe & Leistung

Empfohlene Abmessungen

Kontext	Breite	Hinweise
GitHub README	`width="800"`	Passt in die Inhaltsspalte ohne Scrollen
Dokumentationswebsite	`width="100%"` mit `max-width: 800px`	Responsiv
Blogbeitrag	`width="700"`	Standard-Artikelbreite

Dateigrößen-Richtlinien

Unter 500 KB: Ideal — lädt sofort
500 KB – 2 MB: Gut — akzeptabel für die meisten Verbindungen
2 – 5 MB: Use carefully — add loading="lazy"
Über 5 MB: Erwägen Sie, in kürzere Clips aufzuteilen

GitHub-Einschränkungen

GitHubs Markdown-Renderer bereinigt HTML. Wissen, was erlaubt ist:

Erlaubt	Entfernt
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, Ereignis-Handler
`<details>`/`<summary>` (ausklappbar)	`<form>`, `<input>`

Dateigrößenlimit: GitHub liefert Bilder bis zu 10 MB von externen URLs. AgentGIF GIFs werden von media.agentgif.com (Cloudflare R2 CDN) ausgeliefert, daher gibt es kein GitHub-seitiges Caching-Limit.

Best Practices

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Immer auf die Detailseite verlinken — das <img> in einem <a>-Tag einwickeln, damit Zuschauer das GIF in voller Größe und Metadaten sehen können
Kurz halten — 5-15 Sekunden Demos sind am effektivsten. Lange Aufnahmen verlieren Zuschauer.
Den glücklichen Pfad zeigen — das funktionierende Tool demonstrieren, nicht die Fehlerbehandlung
Ein dunkles Theme verwenden — dunkle Terminal-Themes sehen auf GitHubs weißem und dunklem Hintergrund besser aus
Tape-Datei versionieren — die .tape-Datei zusammen mit dem README committen, damit Sie bei Befehlsänderungen neu aufnehmen können

← Alle Leitfäden · asciinema vs AgentGIF →