Markdown: صيغة GFM الموسعة والرموز التعبيرية

Markdown له نكهات قياسية وموسعة — GitHub Flavored Markdown هو الامتداد الأكثر استخدامًا، مضيفًا العديد من ميزات الصيغة العملية.

1. ما ستتعلمه

• الفرق بين GFM و Markdown القياسي
• الاستخدام الكامل لقوائم المهام
• كيفية إدراج الرموز التعبيرية
• استخدام الهوامش وقوائم التعريفات
• الربط التلقائي والتعرف على URL
• كيفية تجاهل/تخطي صيغة Markdown

2. قصة حقيقية لمسؤول مشروع مفتوح المصدر

(1) نقطة الألم: المشكلات تفتقر إلى المعلومات المنظمة

يدير مورغان مشروعًا مفتوح المصدر بـ 5000+ نجمة ويتلقى عشرات المشكلات كل يوم. الإرسالات فوضوية — بعضها بدون خطوات إعادة الإنتاج، وبعضها ينسى تضمين رسائل الخطأ، وبعضها يضع رموزًا تعبيرية في العناوين مما يجعل التصفية صعبة. يقضي المسؤولون وقتًا طويلاً في سؤال "ما الإصدار الذي تستخدمه؟" و "ما هي رسالة الخطأ الكاملة؟"

(2) الحل: إنشاء قوالب المشكلات باستخدام GFM

أنشأ مورغان قوالب مشكلات GitHub باستخدام قوائم المهام (قوائم التحقق - [ ]) والجداول (معلومات الإصدار/البيئة) وكتل التعليمات البرمجية (سجلات الأخطاء) لتنظيم المعلومات. الرموز التعبيرية تحدد نوع المشكلة: 🐛 خطأ, ✨ ميزة, 📖 توثيق. بعد تفعيل القالب، ارتفع اكتمال المشكلات من 30% إلى 85%، وانخفض متوسط وقت المعالجة إلى النصف.

3. نظرة عامة على GFM

GitHub Flavored Markdown (GFM) هو مجموعة شاملة من Markdown القياسي، مضيفًا امتدادات خاصة بـ GitHub فوق مواصفة CommonMark:

graph TB
    A[GFM - GitHub Flavored Markdown] --> B[معيار CommonMark]
    A --> C[امتدادات GFM]
    C --> D[قوائم المهام]
    C --> E[الجداول]
    C --> F[المشطوب]
    C --> G[الروابط التلقائية]
    C --> H[الرموز التعبيرية]
    C --> I[تخطي الصيغة]

graph TB
    A[GFM - GitHub Flavored Markdown] --> B[معيار CommonMark]
    A --> C[امتدادات GFM]
    C --> D[قوائم المهام]
    C --> E[الجداول]
    C --> F[المشطوب]
    C --> G[الروابط التلقائية]
    C --> H[الرموز التعبيرية]
    C --> I[تخطي الصيغة]

4. الرموز التعبيرية

(1) طريقتان لإدراج الرموز التعبيرية

الطريقة 1 (موصى بها): استخدام الرموز المختصرة المحاطة بنقطتين رأسيتين
:smile: → 😄
:rocket: → 🚀
:warning: → ⚠️

الطريقة 2: لصق أحرف الرموز التعبيرية مباشرة
😄 🚀 ⚠️ ✅ ❌

(2) الرموز التعبيرية الشائعة للتوثيق التقني

✅ تم / ❌ فشل / ⚠️ تحذير
🐛 خطأ / ✨ ميزة جديدة / 📖 توثيق
🚀 إصدار / 🔧 تكوين / 🎨 تنسيق
📦 التبعيات / 🔒 أمان / 📊 بيانات

▶ مثال: استخدام الرموز التعبيرية لتسمية أنواع المشكلات

## قالب المشكلة

### النوع
- 🐛 تقرير خطأ
- ✨ طلب ميزة
- 📖 تحسين التوثيق
- 🔧 مشكلة تكوين

### البيئة
- نظام التشغيل: macOS 14.5
- المتصفح: Chrome 126
- الإصدار: v2.3.1

5. الروابط التلقائية والتعرف على URL

(1) التعرف التلقائي على URL

GFM يحول تلقائيًا عناوين URL إلى روابط قابلة للنقر — لا حاجة لـ <>:

زر https://github.com لمعرفة المزيد.

التوثيق: https://developer.mozilla.org

مستودع المشروع: https://github.com/user/repo

(2) التعرف التلقائي على البريد الإلكتروني

اتصل بنا: support@example.com
بريد المؤلف: author@example.com

6. تجاهل صيغة Markdown

استخدم الشرطة المائلة العكسية \ لتخطي أحرف Markdown الخاصة لتُعرض كنص عادي:

\# هذا ليس عنوانًا — يعرض حرف "#"

\*\*هذا ليس غامقًا\*\*

\- هذا ليس عنصر قائمة

\[هذا ليس رابطًا\](url)

▶ مثال: سيناريوهات التخطي الشائعة

عند كتابة الدروس، تحتاج أحيانًا إلى عرض صيغة Markdown نفسها:

استخدم \`#\` للإشارة إلى عنوان من المستوى الأول.

مثال صيغة: \*\*نص غامق\*\*

في التعليمات البرمجية يكون `**غامق فعلي**` (مغلف بعلامات تنصيص خلفية، لن يُعرض).

7. امتدادات GFM الأخرى

(1) المشطوب

~~هذا النص تم حذفه~~
~~هذه الميزة مهملة~~

(2) تنسيق أغنى داخل الجداول

جداول GFM تدعم التعليمات البرمجية والروابط وأنواع محتوى متعددة:

| الأمر | الوصف | مثال |
|:--------|:------------|:--------|
| `git status` | عرض الحالة | [توثيق][status] |
| `git log` | عرض السجل | وضع مضغوط `--oneline` |
| ~~`git merge`~~ | مهمل | استخدم `rebase` بدلاً من ذلك |

[status]: https://git-scm.com/docs/git-status

(3) تمييز صيغة كتل التعليمات البرمجية المسورة

GFM يدعم تمييز الصيغة لعشرات اللغات:

name: CI Pipeline
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

▶ مثال: اس��خدام diff لعرض تغييرات التعليمات البرمجية

# الإصدار القديم
-    <script src="old-script.js"></script>
# الإصدار الجديد
+    <script src="new-script.min.js" defer></script>

8. مثال كامل: كتابة مشكلة كاملة باستخدام GFM

عنوان المشكلة: شريط التنقل لا يتوسع في Firefox

البيئة:
  نظام التشغيل | Windows 11
  المتصفح | Firefox 128.0
  الإصدار | v3.2.1

خطوات إعادة الإنتاج:
1. افتح التطبيق
2. انقر على قائمة المستخدم في أعلى اليمين
3. فشلت القائمة في التوسع

إخراج السجل:
[2026-06-15 14:32:01] نقر المستخدم على nav-toggle
[2026-06-15 14:32:03] لا استجابة من معالج التبديل

النتيجة المتوقعة: مشكلة GitHub منظمة مع تسميات نوع واضحة (🐛 خطأ)، والبيئة في جدول، وخطوات إعادة الإنتاج في قائمة مرتبة، وقائمة تحقق كقائمة مهام.

❓ أسئلة شائعة

📖 ملخص

• GFM هو امتداد GitHub المستند إلى CommonMark، مضيفًا قوائم المها�� والجداول والمشطوب والمزيد
• يمكن إدراج الرموز التعبيرية عبر :رمز: (GitHub) أو لصقها مباشرة كأحرف
• GFM يتعرف تلقائيًا على URLs ورسائل البريد الإلكتروني — لا حاجة لـ <>
• استخدم \ لتخطي أحرف Markdown الخاصة وعرضها كنص عادي
• علامة اللغة diff تستخدم +/- لعرض تغييرات التعليمات البرمجية
• [TOC] وما شابهها ليست جزءًا من أي معيار أو GFM — إنها ميزات خاصة بالمحرر

📝 تمارين

1. مبتدئ: اكتب مستند اتفاقية رسائل Git commit يستخدم الرموز التعبيرية لتسمية أنواع commit (مثلاً ✨ ميزة 🐛 إصلاح) ويتضمن قائمة مهام كقائمة تحقق قبل commit.

2. متوسط: استخدم علامة اللغة diff لعرض مقارنة قبل/بعد لتغيير تعليمات برمجية (5 أسطر على الأقل، مع إضافات وحذوفات). ثم استخدم الربط التلقائي للإشارة إلى مستودع GitHub.

3. متقدم: أنشئ قالب مشكلة GitHub كامل يجمع بين الجداول (معلومات البيئة) وقوائم المهام (قائمة تحقق) والقوائم المرتبة (خطوات إعادة الإنتاج) وكتل التعليمات البرمجية (السجلات/التكوين) والرموز التعبيرية (تسميات النوع) والاقتباسات (لقطات الشاشة/ملاحظات إضافية).

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

من نحن