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. Badge 임베드

Badge 행에 소형 SVG Badge를 추가하세요:

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

다른 Badge와 조합하세요:

[![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 데모의 최적 위치:

위치	최적 용도
Badge 다음, 설명 전	라이브러리 및 CLI 도구 — 즉각적인 시각적 효과
After "Features" section	복잡한 도구 — 기능이 작동하는 모습 표시
In "Quick Start" section	튜토리얼 — 예상 출력 표시
각 기능 하위 섹션에서	기능이 풍부한 프로젝트 — 기능당 하나의 GIF

가장 효과적인 배치는 Badge 바로 다음, 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와 함께 .tape 파일을 커밋하세요

← 모든 가이드 · asciinema vs AgentGIF →