GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) هو النسخة المحسنة من Markdown من GitHub مع ميزات إضافية مصممة خصيصًا لتطوير البرمجيات والتعاون. يغطي هذا الدليل جميع امتدادات بناء الجملة الخاصة المتاحة على GitHub.

ما هو GitHub Flavored Markdown (GFM)؟

GitHub Flavored Markdown يوسع بناء جملة Markdown الأساسي بميزات تجعله أكثر فائدة لـ:

• التوثيق (READMEs، wikis)
• تتبع المشاكل
• طلبات السحب
• مراجعة الكود
• إدارة المشاريع

ميزات GFM الأساسية

1. كتل الكود المسورة

يدعم GFM كتل الكود المسورة مع تمييز بناء الجملة الخاص باللغة:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. تمييز بناء الجملة

يدعم GitHub تمييز بناء الجملة لمئات اللغات. بعض اللغات الشائعة تشمل:

# Bash script
echo "Hello GitHub!"

# Python script
def greet(name):
    return f"Hello, {name}!"

// Java code
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. قوائم المهام

أنشئ قوائم مهام تفاعلية مع مربعات اختيار:

- [x] إكمال مصادقة المستخدم
- [x] تنفيذ نقاط نهاية API
- [ ] كتابة اختبارات الوحدة
  - [ ] اختبارات الواجهة الخلفية
  - [ ] اختبارات الواجهة الأمامية
- [ ] النشر إلى الإنتاج

• [x] إكمال مصادقة المستخدم
• [x] تنفيذ نقاط نهاية API
• [ ] كتابة اختبارات الوحدة
  • [ ] اختبارات الواجهة الخلفية
  • [ ] اختبارات الواجهة الأمامية
• [ ] النشر إلى الإنتاج

4. الجداول

يوفر GFM بناء جملة بسيط لإنشاء الجداول:

| الميزة            | مدعوم | الوصف                          |
|-------------------|-------|--------------------------------|
| Fenced Code       | ✅    | تمييز خاص باللغة               |
| Task Lists        | ✅    | مربعات اختيار تفاعلية          |
| Tables            | ✅    | عرض البيانات المهيكلة          |
| Mentions          | ✅    | إشعارات المستخدم والفريق       |
| Emoji             | ✅    | تعبيرات بصرية                  |

الميزة	مدعوم	الوصف
Fenced Code	✅	تمييز خاص باللغة
Task Lists	✅	مربعات اختيار تفاعلية
Tables	✅	عرض البيانات المهيكلة
Mentions	✅	إشعارات المستخدم والفريق
Emoji	✅	تعبيرات بصرية

5. الإشارات

أشر إلى المستخدمين أو الفرق لإشعارهم:

@username - الإشارة إلى مستخدم معين
@team-name - الإشارة إلى فريق

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

أضف رموزًا تعبيرية باستخدام الرموز المختصرة:

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. الربط التلقائي

يربط GFM تلقائيًا أنواعًا معينة من المحتوى:

أرقام المشاكل وطلبات السحب

#123 - يربط بالمشكلة 123
PR #456 - يربط بطلب السحب 456

تجزئات SHA

a1b2c3d - يربط بالالتزام بهذا SHA

إشارات المستخدم في المشاكل/طلبات السحب

@username - يربط تلقائيًا بملف المستخدم الشخصي

عناوين URL

https://github.com - يصبح تلقائيًا رابطًا

8. الشطب

يدعم GFM النص المشطوب:

~~هذا النص مشطوب~~

هذا النص مشطوب

9. مراجع الربط التلقائي

ينشئ GFM تلقائيًا روابط لـ:

• عناوين URL لـ HTTP/HTTPS
• عناوين البريد الإلكتروني
• أرقام المشاكل/طلبات السحب على GitHub
• تجزئات SHA للالتزامات

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. تمييز سطر كتلة الكود

تمييز أسطر محددة في كتل الكود:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. تمييز بناء جملة Diff

تمييز التغييرات في الكود باستخدام بناء جملة diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. ترميز خاص بـ GitHub

التنبيهات

استخدم بناء جملة خاص للتنبيهات في وثائق GitHub:

> [!NOTE]
> هذا تنبيه ملاحظة.

> [!TIP]
> هذا تنبيه نصيحة.

> [!IMPORTANT]
> هذا تنبيه مهم.

> [!WARNING]
> هذا تنبيه تحذير.

> [!CAUTION]
> هذا تنبيه حذر.

NOTE

هذا تنبيه ملاحظة.

TIP

هذا تنبيه نصيحة.

IMPORTANT

هذا تنبيه مهم.

WARNING

هذا تنبيه تحذير.

CAUTION

هذا تنبيه حذر.

الروابط النسبية

استخدم الروابط النسبية للتنقل بين الملفات في نفس المستودع:

[README](/ar/README.md)
[إرشادات المساهمة](/ar/CONTRIBUTING.md)
[وثائق API](/ar/docs/api.md)

روابط الصور مع نص التمرير

![GitHub Logo](/ar/images/github-logo.png "GitHub Logo - نص التمرير")

استخدام GFM المتقدم

1. قوائم متداخلة مع قوائم المهام

اجمع القوائم المتداخلة مع قوائم المهام:

## خريطة طريق المشروع

### المرحلة 1: التخطيط
- [x] تحديد نطاق المشروع
- [x] تحديد المتطلبات
  - [x] المتطلبات الوظيفية
  - [x] المتطلبات غير الوظيفية
- [x] إنشاء الجدول الزمني

### المرحلة 2: التطوير
- [x] إعداد هيكل المشروع
- [ ] تنفيذ الميزات الأساسية
  - [x] المصادقة
  - [ ] لوحة التحكم
  - [ ] تكامل API

2. جداول مع رموز تعبيرية وروابط

حسّن الجداول بالرموز التعبيرية والروابط:

| المكون      | الحالة              | المسؤول     |
|-------------|---------------------|-------------|
| المصادقة    | ✅ مستقر            | @johndoe    |
| قاعدة البيانات | ⚠️ يحتاج تحديث   | @janedoe    |
| API         | 🚧 قيد التقدم       | @bobsmith   |
| UI          | ✅ مستقر            | @alicesmith |

المكون	الحالة	المسؤول
المصادقة	✅ مستقر	@johndoe
قاعدة البيانات	⚠️ يحتاج تحديث	@janedoe
API	🚧 قيد التقدم	@bobsmith
UI	✅ مستقر	@alicesmith

3. كتل الكود في القوائم

تضمين كتل الكود داخل القوائم:

1. تثبيت التبعيات:

   ```bash
   npm install

2. تشغيل خادم التطوير:

   npm run dev

3. البناء للإنتاج:

   npm run build

### 4. كتل الاقتباس مع الكود

اجمع الاقتباسات مع كتل الكود:

```markdown
> **نصيحة احترافية:** استخدم الأمر التالي للتحقق بسرعة من حالة Git:
>
> ```bash
> git status
> ```

نصيحة احترافية: استخدم الأمر التالي للتحقق بسرعة من حالة Git:

git status

GFM في سياقات GitHub المختلفة

ملفات README

تدعم ملفات README جميع ميزات GFM ويتم عرضها تلقائيًا على صفحات المستودع.

المشاكل وطلبات السحب

• استخدم قوائم المهام لتتبع التقدم
• أشر إلى أعضاء الفريق للتعاون
• ضمّن مقتطفات الكود مع تمييز بناء الجملة
• أشر إلى المشاكل/طلبات السحب ذات الصلة باستخدام بناء جملة #123

التعليقات

• استخدم الرموز التعبيرية للتفاعلات السريعة
• أشر إلى الأسطر في الكود مع تعليقات السطر
• استخدم كتل الاقتباس للرد على نقاط محددة

Wikis

• نظّم المحتوى باستخدام صفحات متداخلة
• استخدم الجداول للبيانات المهيكلة
• ضمّن أمثلة الكود مع تمييز بناء الجملة

أفضل الممارسات

1. أسلوب الكود

<!-- ✅ جيد -->
```javascript
// استخدم أسماء وظائف وصفية
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. تصميم الجدول

<!-- ✅ جيد -->
| الميزة | الوصف | الحالة |
|--------|-------|--------|
| الميزة 1 | وصف موجز | ✅ |
| الميزة 2 | وصف آخر | 🚧 |

<!-- ❌ تجنب -->
| الميزة | الوصف | الحالة | | | |
|--------|-------|--------|---|---|---|
| الميزة 1 | هذا الوصف طويل جدًا ويجعل الجدول صعب القراءة على الأجهزة المحمولة | ✅ | | | |

3. استخدام قائمة المهام

<!-- ✅ جيد -->
## Sprint Backlog
- [x] إكمال صفحة ملف المستخدم الشخصي
- [ ] تنفيذ وظيفة البحث
  - [x] API الواجهة الخلفية
  - [ ] مكون الواجهة الأمامية
- [ ] كتابة الوثائق

<!-- ❌ تجنب -->
- [ ] المهمة 1
- [ ] المهمة 2
- [ ] المهمة 3
- [ ] المهمة 4
- [ ] المهمة 5
(الكثير من المهام بدون تنظيم)

GFM مقابل Markdown القياسي

الميزة	Markdown القياسي	GitHub Flavored Markdown
كتل الكود المسورة	❌	✅
تمييز بناء الجملة	❌	✅
قوائم المهام	❌	✅
الجداول	❌	✅
الشطب	❌	✅
الرموز التعبيرية	❌	✅
الإشارات	❌	✅
الربط التلقائي	محدود	واسع

أدوات العمل مع GFM

المحررات المحلية

• Visual Studio Code - معاينة GFM والإضافات
• Typora - عرض GFM في الوقت الفعلي
• Mark Text - دعم GFM

الأدوات عبر الإنترنت

• GitHub Gist - إنشاء ومشاركة مقتطفات GFM
• Dillinger - محرر GFM عبر الإنترنت
• StackEdit - دعم GFM مع مزامنة السحابة

أدوات سطر الأوامر

• glow - عارض GFM للterminal
• pandoc - تحويل GFM إلى تنسيقات أخرى
• marked - محلل GFM لـ Node.js

المشاكل الشائعة والإصلاحات

1. كتلة الكود لا يتم تمييزها

المشكلة: كتلة الكود لا تعرض تمييز بناء الجملة

الإصلاح: تأكد من تحديد اللغة الصحيحة:

<!-- ✅ صحيح -->
```javascript
console.log("Hello");

console.log("Hello"); // استخدام jsx بدلاً من javascript للكود غير JSX

### 2. مربعات اختيار قائمة المهام لا تعمل

**المشكلة:** مربعات اختيار قائمة المهام ليست تفاعلية

**الإصلاح:** تأكد من استخدام بناء الجملة الصحيح (مسافة بين `-` و `[ ]`):

```markdown
<!-- ✅ صحيح -->
- [ ] المهمة

<!-- ❌ خطأ -->
-[ ] المهمة (بدون مسافة)
-[x] المهمة (بدون مسافة)

3. الجدول لا يتم عرضه بشكل صحيح

المشكلة: أعمدة الجدول غير محاذاة

الإصلاح: تأكد من محاذاة الأنابيب بشكل صحيح:

<!-- ✅ صحيح -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ خطأ -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

الخطوات التالية

• تعلم بناء جملة Markdown الأساسي
• عرض غش بناء الجملة
• التدريب مع GitHub Gist
• اقرأ وثائق GitHub GFM الرسمية

---

GitHub Flavored Markdown هو أداة قوية للتواصل والتعاون في تطوير البرمجيات. من خلال إتقان هذه الميزات، يمكنك إنشاء وثائق أكثر فعالية، وتتبع المشاكل بشكل أفضل، والتعاون بكفاءة أكبر مع فريقك.