Markdown: صيغة التعليمات البرمجية وكتل التعليمات البرمجية…

التعليمات البرمجية هي قلب التوثيق التقني — يوفر Markdown طريقة أنيقة لتقديمها ليتمكن القراء من قراءتها وتشغيلها.

1. ما ستتعلمه

• صيغة التعليمات البرمجية المضمنة وحالات الاستخدام
• كتل التعليمات البرمجية المسورة وتمييز الصيغة
• كتابة علامات اللغة الصحيحة لكتل التعليمات البرمجية
• تخطي الأحرف الخاصة والتعامل معها في كتل التعليمات البرمجية
• تضمين التعليمات البرمجية داخل القوائم والاقتباسات

2. قصة حقيقية لمطور

(1) نقطة الألم: التعليمات البرمجية المنسوخة من قبل القراء تسبب أخطاء

نشرت نينا دروس Python على مدونتها التقنية، لكن القراء اشتكوا من أن نسخ التعليمات البرمجية وتشغيلها يسبب أخطاء. عند التحقيق، وجدت أن كتل التعليمات البرمجية في منصة مدونتها لا تحتوي على تمييز صيغة — كانت الفواصل والنقاط تبدو متطابقة، وكان بعض الأشخاص ينسخون ( كـ （ (أقواس كاملة العرض). الأسوأ من ذلك، أن بعض كتل التعليمات البرمجية لم تكن تحتوي على تسمية لغة، فظهرت التعليمات البرمجية دون أي تمييز لوني.

(2) الحل: توحيد تنسيق كتل التعليمات البرمجية

انتقلت نينا إلى كتل التعليمات البرمجية المسورة مع علامات اللغة الصحيحة، واختبرت كل مقتطف تعليمات برمجية في بيئة حقيقية قبل النشر. كما أضافت زر "نسخ التعليمات البرمجية". ��عد التبديل، انخفضت تقارير أخطاء القراء بنسبة 90%. حصلت مدونتها على تقدير من عدة وسائل إعلام تقنية بفضل عينات التعليمات البرمجي�� القابلة للتكرار بشكل كبير.

3. التعليمات البرمجية المضمنة

(1) الصيغة الأساسية

غلف النص بعلامة تنصيص خلفية واحدة ` لإنشاء تعليمات برمجية مضمنة:

استخدم الدالة `print()` لإخراج النص.

نفذ `npm install express` في الطرفية.

الوسم `<div>` هو أبسط حاوية في HTML.

(2) الأحرف الخاصة في التعليمات البرمجية المضمنة

لعرض علامة التنصيص الخلفية نفسها، غلفها بعلامتي تنصيص خلفيتين:

استخدم `` ` `` لتمثيل حرف علامة التنصيص الخلفية.

في جملة، استخدم `تعليمات` و `` `علامة تنصيص خلفية` `` معًا.

▶ مثال: الاستخدام الصحيح للتعليمات البرمجية المضمنة

في الملف utils/helpers.py، تُعرف الدالة format_date().
مرر كائن datetime إليها وستعيد سلسلة منسقة.

اضغط F5 لتحديث الصفحة.

4. كتل التعليمات البرمجية المسورة

(1) الصيغة الأساسية

غلف كتلة التعليمات البرمجية بثلاث علامات تنصيص خلفية ``` وحدد بشكل اختياري علامة لغة لتمييز الصيغة:

```python
def greet(name):
    """تحية المستخدم باسمه"""
    return f"مرحبًا، {name}!"

print(greet("أليس"))
```

(2) دور علامات اللغة

# تعليمات Python برمجية مع تمييز الصيغة
def fibonacci(n):
    """حساب الحد النوني من متتالية فيبوناتشي"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))  # الإخراج: 55

5. كتل التعليمات البرمجية المزاحة

بالإضافة إلى كتل التعليمات البرمجية المسورة، يدعم Markdown أيضًا كتل التعليمات البرمجية المزاحة. أزح كل سطر بمقدار 4 مسافات أو مسافة جدولة واحدة:

هذه فقرة.

    // إزاحة 4 مسافات تحول هذا إلى كتلة تعليمات برمجية
    function hello() {
        console.log("مرحبًا!");
    }

العودة إلى النص العادي.

▶ مثال: كتل التعليمات البرمجية المسورة مقابل المزاحة

كتل التعليمات البرمجية المسورة تستخدم ثلاث علامات تنصيص خلفية وتدعم علامات اللغة وتمييز الصيغة.
كتل التعليمات البرمجية المزاحة تستخدم 4 مسافات في ��داية السطر، وتوافقها جيد لكنها لا تدعم تمييز الصيغة.
استخدم كتل التعليمات البرمجية المسورة كلما أمكن.

6. التعامل الخاص في كتل التعليمات البرمجية

(1) تخطي علامات التنصيص الخلفية في كتل التعليمات البرمجية

إذا كانت تعليماتك البرمجية تحتوي على ثلاث علامات تنصيص خلفية، غلفها بعدد أكبر من علامات التنصيص الخلفية:

````text
```python
print("مرحبًا")
```
````

(2) التفاف الأسطر الطويلة من التعليمات البرمجية

# موصى به: حافظ على كل سطر ضمن 80 حرفًا
const result = await api.getUserData(userId)
  .then(data => processData(data))
  .catch(error => handleError(error));

# تجنب: الأسطر الطويلة جدًا غير ا��ملتفة
const result = await api.getUserData(userId).then(data => processData(data)).catch(error => handleError(error));

▶ مثال: مؤشرات الأخطاء الشائعة في كتل التعليمات البرمجية

❌ الطريقة الخاطئة:
كتل التعليمات البرمجية بدون علامات لغة تظهر كنص أسود على خلفية بيضاء

✅ الطريقة الصحيحة:
كتل التعليمات البرمجية مع علامة لغة python تعرض تمييز صيغة ملون

7. تضمين التعليمات البرمجية في القوائم والاقتباسات

(1) كتل التعليمات البرمجية داخل القوائم

تحتاج كتل التعليمات البرمجية داخل القوائم إلى إزاحة إضافية بمقدار 8 مسافات (أو مسافتي جدولة):

- نفذ الاختبارات:

        npm test -- --coverage

- تحقق من التنسيق:

        npx eslint src/ --fix

(2) كتل التعليمات البرمجية داخل الاقتباسات

> **التنفيذ الأساسي:**
>
> ```python
> def process_data(df):
>     """تنظيف البيانات وتجميعها"""
>     return df.dropna().groupby("category").sum()
> ```
>
> التعليمات البرمجية أعلاه تنظف القيم الفارغة ثم تجمع وتلخص.

8. مثال كامل: صفحة توثيق تعليمات برمجية

نظرة عامة على برنامج معالجة البيانات

تثبيت التبعيات: pip install pandas numpy matplotlib

دالة load_data(): تحميل البيانات من ملف CSV
دالة clean_data(): إزالة القيم الفارغة والصفوف المكررة

سير العمل الكامل:
1. تحميل البيانات - load_data("sales.csv")
2. التنظيف - clean_data(data)
3. إخراج الإحصائيات - طباعة عدد الصفوف وأسماء الأعمدة

النتيجة المتوقعة: مستند تقني نظيف مع تعليمات برمجية وشروحات تتناوب بسلاسة، وعلامات لغة صحيحة، وتقسيم واضح للعمل بين التعليمات البرمجية المضمنة وكتل التعليمات البرمجية.

❓ أسئلة شائعة

📖 ملخص

• التعليمات البرمجية المضمنة تستخدم علامة تنصيص خلفية واحدة؛ كتل التعليمات البرمجية تستخدم ثلاث علامات تنصيص خلفية
• أضف دائمًا علامة لغة لكتل التعليمات البرمجية لتمييز الصي��ة
• كتل التعليمات البرمجية المزاحة (4 مسافات) لم تعد موصى بها — فضل النمط المسور
• كتل التعليمات البرمجية داخل القوائم تحتاج إلى إزاحة إضافية
• تخطى علامات التنصيص الخلفية داخل كتل التعليمات البرمجية بالتغليف بعدد أكبر من علامات التنصيص الخلفية
• جميع الإزاحات والمسافات البيضاء في كتل التعليمات البرمجية تُحفظ بالكامل

📝 تمارين

1. أساسي: اكتب قسمًا في Markdown يتضمن 3 مقتطفات تعليمات برمجية مضمنة (اسم ملف، اسم دالة، اختصار لوحة مفاتيح) وكتلة تعليمات برمجية واحدة مع علامة لغة.

2. متوسط: أنشئ بنية متداخلة في مستند Markdown — ضع كتلة تعليمات برمجية داخل عنصر قائمة غير مرتبة، وضع كتلة تعليمات برمجية داخل اقتباس.

3. متقدم: اكتب قسمًا في Markdown بثلاثة مستويات من تداخل علامات التنصيص الخلفية (موضحًا كيفية عرض كتلة تعليمات برمجية تعرض بدورها كتلة تعليمات برمجية)، واستخدم أربع علامات تنصيص خلفية للغلاف الخارجي لضمان العرض الصحيح.

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

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

من نحن