كيف تتقن لغة Markdown كمدون للتقنية

كيف تتقن لغة  Markdown كمدون للتقنية

mastering-tech-markdown

1- مقدمة عن Markdown

ما هي Markdown؟

ببساطة، Markdown هي لغة ترميز خفيفة الوزن (Lightweight Markup Language) أنشأها "جون غروبر" بالتعاون مع "آرون سوارتز". تهدف إلى تمكينك من كتابة محتوى منسق باستخدام محرر نصوص عادي، بحيث يكون النص المصدر سهل القراءة والكتابة في حد ذاته.

لماذا هي مهمة؟

• البساطة والتركيز: تسمح لك بالتركيز على المحتوى (الكتابة) بدلاً من التنسيق (النقر على الأزرار).
• سهولة القراءة: النص المكتوب بـ Markdown مقروء جدًا حتى قبل تحويله.
• قابلية التحويل: يمكن تحويل مستندات Markdown بسهولة إلى العديد من التنسيقات الأخرى مثل HTML، PDF، و Word.
• الانتشار الواسع: تُستخدم في كل مكان: منصات مثل GitHub (في ملفات README والتعليقات)، تطبيقات الملاحظات (Notion, Obsidian)، منتديات النقاش (Reddit)، وأنظمة إدارة المحتوى.

2- التركيب الأساسي لـ Markdown (Basic Syntax)

العناوين (Headings):
تستخدم علامة # لإنشاء العناوين. عدد العلامات يحدد مستوى العنوان (من 1 إلى 6).

# هذا عنوان من المستوى الأول (H1)
## هذا عنوان من المستوى الثاني (H2)
### هذا عنوان من المستوى الثالث (H3)
#### هذا عنوان من المستوى الرابع (H4)
##### هذا عنوان من المستوى الخامس (H5)
###### هذا عنوان من المستوى السادس (H6)
    

الفقرات والأسطر الجديدة (Paragraphs & Line Breaks):

الفقرات: اترك سطرًا فارغًا بين الفقرات.

الأسطر الجديدة: لإنشاء فاصل أسطر (line break) داخل نفس الفقرة، اترك مسافتين في نهاية السطر ثم اضغط Enter.

التنسيق الأساسي للنص:

• الخط العريض (Bold): **نص عريض** أو __نص عريض__
• الخط المائل (Italic): *نص مائل* أو _نص مائل_
• عريض ومائل معًا: ***نص عريض ومائل***
• خط يتوسطه خط (Strikethrough): ~~نص مشطوب~~ (هذه الميزة جزء من امتدادات Markdown الشائعة).

3- القوائم (Lists)

القوائم غير المرتبة (Unordered Lists):
استخدم *، -، أو + متبوعة بمسافة. يمكنك إنشاء قوائم متداخلة عن طريق إضافة مسافة بادئة (indentation).

* عنصر أول
* عنصر ثاني
  - عنصر فرعي 1
  - عنصر فرعي 2
* عنصر ثالث
    

القوائم المرتبة (Ordered Lists):

استخدم الأرقام متبوعة بنقطة. الميزة الرائعة هنا هي أنك لست بحاجة إلى ترقيمها بشكل صحيح؛ سيقوم Markdown بذلك تلقائيًا.

1. الخطوة الأولى
2. الخطوة الثانية
3. الخطوة الثالثة

أو يمكنك كتابة:

1. الخطوة الأولى
1. الخطوة الثانية
1. الخطوة الثالث

والنتيجة ستكون قائمة مرقمة بشكل صحيح.

4- الروابط والصور (Links & Images)

الروابط (Links):
التركيب هو [نص الرابط الظاهر](رابط الموقع).

لزيارة جوجل، اضغط على [هذا الرابط](https://www.google.com).

الصور (Images):

تشبه الروابط كثيرًا، ولكن مع علامة تعجب ! في البداية. التركيب هو . النص البديل مهم لإمكانية الوصول ولمحركات البحث.

 ![شعار Markdown](https://markdown-here.com/img/icon256.png)

5- الجداول (Tables)

تُعد الجداول من الميزات القوية، خاصة في التوثيق التقني.

• استخدم الشرطة المستقيمة | للفصل بين الأعمدة.
• استخدم ثلاثة شرطات أو أكثر --- للفصل بين رأس الجدول وبقية الصفوف.
• استخدم النقطتين : للتحكم في محاذاة النص داخل الأعمدة.

      | المحاذاة لليسار | المحاذاة للوسط | المحاذاة لليمين |
| :-------------- | :-------------: | --------------: |
| نص             | نص              | نص              |
| مثال آخر        | مثال آخر        | مثال آخر        |
    

6- الأكواد البرمجية (Code)

هذا الجزء حيوي للمطورين.

كود داخل السطر (Inline Code):
لتضمين اسم متغير أو أمر قصير داخل فقرة، استخدم علامتي الاقتباس الخلفية `.

  لتثبيت الحزمة، استخدم الأمر `npm install express`.

كتل الأكواد البرمجية (Fenced Code Blocks):
لعرض كتلة كاملة من الكود، استخدم ثلاث علامات اقتباس خلفية ``` قبل وبعد الكود. يمكنك أيضًا تحديد لغة البرمجة لتفعيل تمييز الصيغة (Syntax Highlighting).

```javascript

function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet('World');

```

7- الامتدادات والمكتبات (Extensions)

Markdown الأساسي بسيط جدًا. معظم المنصات الحديثة تستخدم امتدادات تضيف ميزات قوية. أشهرها هو GitHub Flavored Markdown (GFM)، والذي يضيف:

• الجداول (كما شرحنا أعلاه).
• خط يتوسطه خط (~~text~~).
• قوائم المهام (Task Lists):

- [x] إنهاء الدرس الأول

- [ ] بدء الدرس الثاني

- [ ] أخذ استراحة

• الربط التلقائي للروابط (فقط اكتب https://www.github.com وسيتحول إلى رابط).

8- الأدوات والتطبيقات (Tools & Editors)

• محررات النصوص:

• Visual Studio Code (VS Code): أفضل خيار للمطورين. يحتوي على معاينة مدمجة لملفات Markdown، وهناك إضافات رائعة مثل "Markdown All in One" التي تسهل كل شيء.

• المحررات المتخصصة عبر الإنترنت:

• StackEdit.io أو Dillinger.io: تتيح لك الكتابة والمعاينة مباشرة في المتصفح.

• تطبيقات تدوين الملاحظات:

• Obsidian و Joplin: تطبيقات قوية مبنية بالكامل على ملفات Markdown المحلية.
• Notion: يدعم Markdown كاختصارات للكتابة السريعة.

9- أفضل الممارسات (Best Practices)

1. استخدم سطرًا فارغًا بين العناصر المختلفة (مثل فقرة وقائمة، أو عنوان وفقرة) لتحسين قابلية القراءة.
2. اجعل طول الأسطر معقولًا (حوالي 80 حرفًا) لتسهيل قراءة الملف الأصلي في أي محرر.
3. استخدم العناوين بشكل هرمي ومنطقي (لا تقفز من H1 إلى H4).
4. دائمًا أضف نصًا بديلاً (Alt Text) للصور.
5. أضف تعليقات إذا كان المستند معقدًا باستخدام صيغة تعليقات HTML: <!-- هذا تعليق لن يظهر في النسخة النهائية -->.

10- تمارين عملية (Practical Exercises)

التمرين الأول: إنشاء ملف شخصي بسيط
قم بإنشاء ملف Markdown يحتوي على:

1. اسمك كعنوان من المستوى الأول (H1).
2. نبذة قصيرة عنك في فقرة، مع جعل اسم مهنتك بخط عريض.
3. قائمة غير مرتبة لـ 3 من هواياتك.
4. رابط إلى حسابك على LinkedIn أو GitHub.

التمرين الثاني: توثيق دالة برمجية
اكتب توثيقًا لدالة برمجية افتراضية، بحيث يحتوي على:

1. اسم الدالة كعنوان من المستوى الثالث (H3).
2. شرح قصير لعمل الدالة.
3. جدول يوضح المعلمات (Parameters) التي تستقبلها الدالة (اسم المعلمة، نوعها، ووصفها).
4. كتلة كود (Code Block) مع تمييز الصيغة (Syntax Highlighting) توضح مثالًا على كيفية استخدام الدالة.

التمرين الثالث: إنشاء ملف README لمشروع
هذا هو التطبيق الأكثر شيوعًا. قم بإنشاء ملف README.md لمشروع افتراضي، ويجب أن يحتوي على:

1. اسم المشروع كعنوان رئيسي.
2. فقرة تصف المشروع.
3. عنوان "الميزات" (Features) متبوعًا بقائمة مرتبة بالميزات الرئيسية.
4. عنوان "كيفية التثبيت" (Installation) متبوعًا بكتلة كود تحتوي على الأوامر اللازمة للتثبيت (مثل git clone و npm install).
5. صورة لشعار المشروع أو لقطة شاشة.

آمل أن يكون هذا الدرس قد قدم لك رؤية واضحة وشاملة حول قوة وبساطة Markdown. الآن، أفضل طريقة للتعلم هي البدء في التطبيق. حظًا موفقًا

بالتأكيد! إليك حلول مفصلة للتمارين العملية التي تم اقتراحها في درس Markdown، مع شرح لكل جزء لتوضيح كيفية تطبيق القواعد التي تعلمناها.

حل التمارين:

حل التمرين الأول: إنشاء ملف شخصي بسيط

المتطلبات:

1. اسمك كعنوان من المستوى الأول (H1).
2. نبذة قصيرة عنك في فقرة، مع جعل اسم مهنتك بخط عريض.
3. قائمة غير مرتبة لـ 3 من هواياتك.
4. رابط إلى حسابك على LinkedIn أو GitHub.

الحل المقترح (الكود):

شرح الحل:

• # أحمد محمد: تم استخدام علامة # واحدة لجعل الاسم عنوانًا من المستوى الأول (H1).
• أنا **مطور برامج**...: النص عبارة عن فقرة عادية. تم وضع نجمتين مزدوجتين ** حول عبارة "مطور برامج" لجعلها بخط عريض (Bold).
• - القراءة: تم استخدام الشرطة - متبوعة بمسافة لإنشاء عنصر في قائمة غير مرتبة. تم تكرار ذلك لجميع الهوايات.
• [حسابي على GitHub](...): تم استخدام صيغة الروابط [النص الظاهر](الرابط) لإدراج رابط تشعبي إلى حساب GitHub.

حل التمرين الثاني: توثيق دالة برمجية

المتطلبات:

1. اسم الدالة كعنوان من المستوى الثالث (H3).
2. شرح قصير لعمل الدالة.
3. جدول يوضح المعلمات (Parameters) التي تستقبلها الدالة.
4. كتلة كود (Code Block) توضح مثالًا على استخدام الدالة.

الحل المقترح (الكود):

شرح الحل:

• ### دالة \calculateTotalPrice`: تم استخدام ثلاث علامات ###لإنشاء عنوان من المستوى الثالث (H3). تم وضع اسم الدالة بين علامتي الاقتباس الخلفية `` `` لتمييزه ككود داخل السطر (Inline Code).
• الجدول: تم إنشاء جدول باستخدام الشرطة المستقيمة | للفصل بين الأعمدة. السطر الثاني | :--- | :---: | :--- | هو سطر الفاصل الذي يحدد رؤوس الأعمدة، واستخدام النقطتين : يتحكم في محاذاة النص (يسار، وسط، يمين).
• items و taxRate: تم تمييز أسماء المعلمات داخل الجدول كـ Inline Code أيضًا.
• كتلة الكود: تم استخدام ثلاث علامات اقتباس خلفية ``` متبوعة باسم لغة البرمجة javascript لإنشاء كتلة كود مع تمييز الصيغة (Syntax Highlighting). هذا يجعل الكود أسهل في القراءة والفهم.

حل التمرين الثالث: إنشاء ملف README لمشروع

المتطلبات:

1. اسم المشروع كعنوان رئيسي.
2. فقرة تصف المشروع.
3. عنوان "الميزات" متبوعًا بقائمة مرتبة.
4. عنوان "كيفية التثبيت" متبوعًا بكتلة كود.
5. صورة لشعار المشروع أو لقطة شاشة.

الحل المقترح (الكود):

لقطة شاشة

![alt text](https://via.placeholder.com/600x400.png?text=App+Screenshot)

**شرح الحل:**

*   `# مدير المهام البسيط`: عنوان رئيسي للمشروع باستخدام `H1`.
*   `![شعار مدير المهام](...)`: تم إدراج صورة باستخدام الصيغة `![النص البديل](رابط الصورة)`. تم استخدام رابط وهمي من `placeholder.com` كمثال.
*   `## الميزات`: عنوان فرعي (`H2`) باستخدام `##`.
*   `1. إضافة مهام...`: تم استخدام الأرقام متبوعة بنقطة لإنشاء **قائمة مرتبة** توضح ميزات المشروع.
*   `## كيفية التثبيت`: عنوان فرعي آخر.
*   ```bash ... ```: تم إنشاء كتلة كود تحتوي على أوامر الطرفية (Terminal). تم استخدام `bash` لتفعيل التمييز اللوني المناسب لأوامر Shell.
*   تمت إضافة تعليقات داخل كتلة الكود باستخدام `#` لتوضيح كل أمر، وهي ممارسة جيدة في ملفات README.
*   تمت إضافة قسم آخر للقطة شاشة لتوضيح كيفية إدراج الصور الأكبر حجمًا.

أتمنى أن تكون هذه الحلول واضحة ومفيدة في تطبيق ما تعلمته عن Markdown .