How to Embed GIFs in GitHub README

البدء السريع

أسرع طريقة لإضافة عرض توضيحي من AgentGIF إلى 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 بمعرف التسجيل المكون من 8 أحرف. ينشئ هذا تسجيلاً مركزياً محدود العرض يشير إلى صفحة التفاصيل.

1. تضمين Markdown

صيغة صورة Markdown القياسية. بسيطة لكن محاذاة لليسار وعرض غير محدود:

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

المزايا: Markdown خالص، يعمل في كل مكان.
العيوب: محاذاة لليسار، عرض كامل على الشاشات العريضة.

2. تضمين HTML مركزي (موصى به)

ملفات GitHub README تدعم مجموعة فرعية من HTML. استخدم هذا للتسجيلات المركزية ذات العرض المتحكم به:

<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 يصف العرض التوضيحي للوصول وتحسين محركات البحث

هذه الصيغة التي تستخدمها معظم مشاريع المصدر المفتوح للعروض التوضيحية في 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 وسوم <iframe> من ملفات README. استخدم هذه الطريقة لمواقع التوثيق (Docusaurus، MkDocs، VitePress) والمدونات فقط.

4. Script Widget

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

ملاحظة: يحذف GitHub وسوم <script>. استخدم لموقعك الخاص أو مواقع التوثيق التي تسمح بالسكريبتات.

5. تضمين الشارة

أضف شارة SVG مضغوطة إلى صف شاراتك:

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

ادمج مع شارات أخرى:

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

الصق رابط AgentGIF في المنصات التي تدعم oEmbed (Notion، Slack، Discord). تكتشف المنصة بيانات التضمين الوصفية تلقائياً وتعرض معاينة غنية.

أين تضع العرض التوضيحي

أفضل موضع لعرض GIF التوضيحي في README:

أكثر موضع فعالاً هو قرب أعلى README، مباشرةً بعد الشارات. يقرر الزوار لأول مرة في غضون ثوانٍ ما إذا كانوا سيكملون القراءة — عرض GIF مُصمَّم بعناية يوصل فوراً ما يفعله مشروعك.

الحجم والأداء

الأبعاد الموصى بها

إرشادات حجم الملف

• أقل من 500 KB: مثالي — يُحمَّل فوراً
• 500 KB – 2 MB: جيد — مقبول لمعظم الاتصالات
• 2 – 5 MB: Use carefully — add loading="lazy"
• أكثر من 5 MB: فكر في تقسيمه إلى مقاطع أقصر

قيود GitHub

يُعقّم معالج Markdown في GitHub HTML. اعرف ما هو مسموح به:

حد حجم الملف: يخدم GitHub صوراً تصل إلى 10 MB من الروابط الخارجية. تُخدَّم تسجيلات 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> حتى يتمكن المشاهدون من رؤية التسجيل بالحجم الكامل والبيانات الوصفية
3. اجعله قصيراً — العروض التوضيحية من 5 إلى 15 ثانية هي الأكثر فعالية. التسجيلات الطويلة تفقد المشاهدين.
4. اعرض المسار السعيد — أظهر الأداة وهي تعمل، وليس معالجة الأخطاء
5. استخدم ثيماً داكناً — ثيمات الطرفية الداكنة تبدو أفضل على خلفيات GitHub البيضاء والداكنة
6. اضبط إصدار ملف الـ tape — احفظ ملف .tape جنباً إلى جنب مع README حتى تتمكن من إعادة التسجيل عند تغيير الأوامر