How to Embed GIFs in GitHub README

Bắt đầu nhanh

Cách nhanh nhất để thêm demo AgentGIF vào README của bạn:

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

Thay YOUR_ID bằng ID 8 ký tự của GIF. Điều này tạo ra GIF căn giữa, giới hạn chiều rộng, liên kết đến trang chi tiết.

1. Nhúng Markdown

Cú pháp hình ảnh Markdown tiêu chuẩn. Đơn giản nhưng căn trái và chiều rộng không giới hạn:

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

Ưu điểm: Markdown thuần, hoạt động ở mọi nơi.
Nhược điểm: Căn trái, chiều rộng đầy đủ trên màn hình rộng.

2. Nhúng HTML căn giữa (Khuyến nghị)

Tệp GitHub README hỗ trợ một tập con HTML. Dùng điều này cho GIF căn giữa với chiều rộng có kiểm soát:

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

Tại sao điều này hoạt động:

• align="center" — centers the block on GitHub
• width="800" — constrains maximum width (scales down on mobile)
• Bọc <a> liên kết đến trang chi tiết AgentGIF
• Văn bản alt mô tả demo cho khả năng truy cập và SEO

Đây là định dạng được hầu hết các dự án mã nguồn mở dùng cho demo README.

Với chú thích

<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. Nhúng iframe

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

Lưu ý: GitHub loại bỏ thẻ <iframe> từ tệp README. Chỉ dùng phương pháp này cho các trang tài liệu (Docusaurus, MkDocs, VitePress) và bài đăng blog.

4. Script Widget

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

Lưu ý: GitHub loại bỏ thẻ <script>. Dùng cho trang web của bạn hoặc các trang tài liệu cho phép script.

5. Nhúng Badge

Thêm badge SVG nhỏ gọn vào hàng badge của bạn:

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

Kết hợp với các badge khác:

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

Dán URL AgentGIF vào các nền tảng hỗ trợ oEmbed (Notion, Slack, Discord). Nền tảng tự động khám phá metadata nhúng và hiển thị bản xem trước phong phú.

Đặt demo ở đâu

Vị trí tốt nhất cho demo GIF trong README:

Vị trí hiệu quả nhất là gần đầu README, ngay sau badge. Người truy cập lần đầu quyết định trong vài giây có tiếp tục đọc hay không — một demo GIF được làm tốt ngay lập tức truyền đạt dự án của bạn làm gì.

Kích thước & Hiệu suất

Kích thước khuyến nghị

Hướng dẫn kích thước tệp

• Dưới 500 KB: Lý tưởng — tải ngay lập tức
• 500 KB – 2 MB: Tốt — chấp nhận được cho hầu hết kết nối
• 2 – 5 MB: Use carefully — add loading="lazy"
• Trên 5 MB: Cân nhắc chia thành các đoạn ngắn hơn

Giới hạn GitHub

Trình hiển thị Markdown của GitHub làm sạch HTML. Biết những gì được phép:

Giới hạn kích thước tệp: GitHub phục vụ hình ảnh đến 10 MB từ URL ngoài. GIF AgentGIF được phục vụ từ media.agentgif.com (Cloudflare R2 CDN), vì vậy không có giới hạn bộ nhớ đệm phía GitHub.

Thực tiễn tốt nhất

1. Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
2. Luôn liên kết đến trang chi tiết — bọc <img> trong thẻ <a> để người xem có thể thấy GIF kích thước đầy đủ và metadata
3. Giữ ngắn gọn — demo 5-15 giây hiệu quả nhất. Bản ghi dài làm mất người xem.
4. Hiển thị trường hợp thành công — trình diễn công cụ hoạt động, không phải xử lý lỗi
5. Dùng theme tối — theme terminal tối trông đẹp hơn trên nền trắng và tối của GitHub
6. Kiểm soát phiên bản tệp tape — commit tệp .tape cùng với README để bạn có thể ghi lại khi lệnh thay đổi