How to Embed GIFs in GitHub README

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

Démarrage rapide

La façon la plus rapide d'ajouter une démo AgentGIF à votre 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>

Remplacez YOUR_ID par l'identifiant GIF de 8 caractères. Ceci crée un GIF centré à largeur contrainte qui renvoie à la page de détail.

1. Intégration Markdown

Syntaxe d'image Markdown standard. Simple mais aligné à gauche et largeur non contrainte :

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

Avantages : Markdown pur, fonctionne partout.
Inconvénients : Aligné à gauche, pleine largeur sur les grands écrans.

2. Intégration HTML centrée (recommandée)

Les fichiers README GitHub prennent en charge un sous-ensemble de HTML. Utilisez ceci pour des GIF centrés avec une largeur contrôlée :

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

Pourquoi cela fonctionne :

align="center" — centers the block on GitHub
width="800" — constrains maximum width (scales down on mobile)
L'encapsuleur <a> renvoie à la page de détail AgentGIF
Le texte alt décrit la démo pour l'accessibilité et le SEO

C'est le format utilisé par la plupart des projets open source pour les démos README.

Avec une légende

<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. Intégration iframe

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

Remarque : GitHub supprime les balises <iframe> des fichiers README. Utilisez cette méthode uniquement pour les sites de documentation (Docusaurus, MkDocs, VitePress) et les billets de blog.

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

Remarque : GitHub supprime les balises <script>. Utilisez pour votre propre site web ou les sites de documentation qui autorisent les scripts.

5. Intégration de badge

Ajoutez un badge SVG compact à votre rangée de badges :

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

Combinez avec d'autres badges :

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

Collez une URL AgentGIF dans des plateformes qui prennent en charge oEmbed (Notion, Slack, Discord). La plateforme découvre automatiquement les métadonnées d'intégration et affiche un aperçu enrichi.

Où placer la démo

La meilleure position pour une démo GIF dans un README :

Position	Idéal pour
Après les badges, avant la description	Bibliothèques et outils CLI — impact visuel immédiat
After "Features" section	Outils complexes — montrer les fonctionnalités en action
In "Quick Start" section	Tutoriels — montrer la sortie attendue
Dans chaque sous-section de fonctionnalité	Projets riches en fonctionnalités — un GIF par fonctionnalité

Le placement le plus efficace est près du haut du README, juste après les badges. Les visiteurs décident en quelques secondes s'ils continuent à lire — une démo GIF bien conçue communique instantanément ce que fait votre projet.

Dimensionnement et performance

Dimensions recommandées

Contexte	Largeur	Remarques
README GitHub	`width="800"`	S'adapte à la colonne de contenu sans défilement
Site de documentation	`width="100%"` avec `max-width: 800px`	Réactif
Billet de blog	`width="700"`	Largeur d'article standard

Directives de taille de fichier

Moins de 500 Ko : Idéal — se charge instantanément
500 Ko – 2 Mo : Bon — acceptable pour la plupart des connexions
2 – 5 MB: Use carefully — add loading="lazy"
Plus de 5 Mo : Envisagez de diviser en clips plus courts

Limitations de GitHub

Le moteur Markdown de GitHub assainit le HTML. Sachez ce qui est autorisé :

Autorisé	Supprimé
`<img>`, `<a>`, `<p>`, `<br>`	`<iframe>`, `<script>`, `<style>`
`align`, `width`, `height`, `alt`, `src`	`onclick`, `onerror`, gestionnaires d'événements
`<details>`/`<summary>` (repliable)	`<form>`, `<input>`

Limite de taille de fichier : GitHub sert des images jusqu'à 10 Mo depuis des URL externes. Les GIF AgentGIF sont servis depuis media.agentgif.com (CDN Cloudflare R2), donc il n'y a pas de limite de mise en cache côté GitHub.

Meilleures pratiques

Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
Créez toujours un lien vers la page de détail — encapsulez <img> dans une balise <a> pour que les spectateurs puissent voir le GIF en taille réelle et les métadonnées
Restez concis — les démos de 5 à 15 secondes sont les plus efficaces. Les longs enregistrements font fuir les spectateurs.
Montrez le cas nominal — démontrez le fonctionnement de l'outil, pas la gestion des erreurs
Utilisez un thème sombre — les thèmes terminal sombres s'affichent mieux sur les fonds blanc et sombre de GitHub
Versionnez votre fichier tape — commitez le fichier .tape à côté du README pour pouvoir réenregistrer lorsque les commandes changent

← Tous les guides · asciinema vs AgentGIF →