How to Embed GIFs in GitHub README

เริ่มต้นอย่างรวดเร็ว

วิธีที่เร็วที่สุดในการเพิ่ม AgentGIF demo ลงใน 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>

แทนที่ YOUR_ID ด้วย ID 8 ตัวอักษรของ GIF ของคุณ จะสร้าง GIF กึ่งกลางที่จำกัดความกว้างและลิงก์ไปยังหน้ารายละเอียด

1. Markdown Embed

ไวยากรณ์รูปภาพ Markdown มาตรฐาน ง่ายแต่จัดชิดซ้ายและไม่จำกัดความกว้าง:

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

ข้อดี: Markdown บริสุทธิ์ ใช้งานได้ทุกที่
ข้อเสีย: จัดชิดซ้าย ความกว้างเต็มบนหน้าจอกว้าง

2. HTML Embed แบบกึ่งกลาง (แนะนำ)

ไฟล์ GitHub README รองรับ HTML บางส่วน ใช้แบบนี้สำหรับ GIFs กึ่งกลางที่ควบคุมความกว้าง:

<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)
• wrapper <a> ลิงก์ไปยังหน้ารายละเอียด AgentGIF
• ข้อความ alt อธิบาย demo สำหรับการเข้าถึงและ SEO

นี่คือรูปแบบที่โปรเจกต์ open-source ส่วนใหญ่ใช้สำหรับ README demos

พร้อม Caption

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

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

หมายเหตุ: GitHub ลบแท็ก <iframe> จากไฟล์ README ใช้วิธีนี้สำหรับเว็บไซต์เอกสาร (Docusaurus, MkDocs, VitePress) และบล็อกโพสต์เท่านั้น

4. Script Widget

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

หมายเหตุ: GitHub ลบแท็ก <script> ใช้สำหรับเว็บไซต์ของคุณหรือเว็บไซต์เอกสารที่อนุญาต scripts

5. Badge Embed

เพิ่ม SVG badge ขนาดกะทัดรัดลงในแถว badge ของคุณ:

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

รวมกับ 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

วาง URL ของ AgentGIF ลงในแพลตฟอร์มที่รองรับ oEmbed (Notion, Slack, Discord) แพลตฟอร์มจะค้นพบ embed metadata โดยอัตโนมัติและเรนเดอร์ตัวอย่างที่สมบูรณ์

ตำแหน่งที่วาง Demo

ตำแหน่งที่ดีที่สุดสำหรับ GIF demo ใน README:

การวางที่มีประสิทธิภาพมากที่สุดคือใกล้ด้านบนของ README ทันทีหลัง badges ผู้เยี่ยมชมครั้งแรกตัดสินใจภายในไม่กี่วินาทีว่าจะอ่านต่อหรือไม่ — GIF demo ที่ทำดีจะสื่อสารทันทีว่าโปรเจกต์ของคุณทำอะไร

ขนาดและประสิทธิภาพ

ขนาดที่แนะนำ

แนวทางขนาดไฟล์

• ต่ำกว่า 500 KB: ดีที่สุด — โหลดทันที
• 500 KB – 2 MB: ดี — ยอมรับได้สำหรับการเชื่อมต่อส่วนใหญ่
• 2 – 5 MB: Use carefully — add loading="lazy"
• เกิน 5 MB: พิจารณาแยกเป็นคลิปสั้นๆ

ข้อจำกัดของ GitHub

ตัวเรนเดอร์ Markdown ของ GitHub กรอง HTML รู้ว่าอะไรที่อนุญาต:

ขีดจำกัดขนาดไฟล์: GitHub แสดงรูปภาพสูงสุด 10 MB จาก URL ภายนอก GIFs ของ AgentGIF แสดงจาก media.agentgif.com (Cloudflare R2 CDN) ดังนั้นไม่มีขีดจำกัดการแคชของ GitHub

แนวปฏิบัติที่ดีที่สุด

1. Write descriptive alt text — alt="jq demo showing JSON pretty-printing and field extraction" not alt="demo"
2. ลิงก์ไปยังหน้ารายละเอียดเสมอ — ห่อ <img> ในแท็ก <a> เพื่อให้ผู้ชมเห็น GIF ขนาดเต็มและ metadata
3. รักษาให้สั้น — demos 5-15 วินาทีมีประสิทธิภาพมากที่สุด การบันทึกที่ยาวทำให้ผู้ชมเลิกดู
4. แสดงเส้นทางที่ราบรื่น — สาธิตเครื่องมือที่ทำงานได้ ไม่ใช่การจัดการข้อผิดพลาด
5. ใช้ธีมมืด — ธีม terminal มืดดูดีกว่าบนพื้นหลังขาวและมืดของ GitHub
6. จัดเวอร์ชันไฟล์ tape ของคุณ — commit ไฟล์ .tape ควบคู่กับ README เพื่อให้คุณสามารถบันทึกใหม่เมื่อคำสั่งเปลี่ยนแปลง