مقدمة إلى Markdown

Markdown هي لغة ترميز خفيفة الوزن تُمكّنك من الكتابة بنص بسيط سهل القراءة والكتابة ثم تحويله إلى HTML منظم (وغيره من الصيغ). أُنشئت عام 2004 على يد John Gruber، وأصبحت من أشهر لغات الترميز على الويب.

ما هو Markdown؟

Markdown هي صياغة تنسيق لنصوص صِرفة تُمكّنك من إضافة عناصر تنسيق إلى مستندات نصية. بخلاف HTML أو XML، تستخدم علامات بسيطة لبناء مستند منظم.

الميزات الرئيسية:

• سهل القراءة: ملفات Markdown قابلة للقراءة حتى بصيغتها الخام
• غير مقيد بالمنصات: يعمل عبر أنظمة التشغيل والتطبيقات
• قابل للتحويل: يمكن تحويله إلى HTML وPDF وWord وغيرها
• صديق لإدارة الإصدارات: نص صِرف يتكامل جيداً مع Git وغيرها
• سرعة في الكتابة: قواعد قليلة تعني تحريراً أسرع

أمثلة على القواعد الأساسية:

# عنوان 1
## عنوان 2
### عنوان 3

**نص عريض** و*نص مائل*

- عنصر قائمة غير مرتبة
- عنصر آخر

1. عنصر قائمة مرتبة
2. عنصر آخر

[نص رابط](https://www.markdownlang.com)

`شفرة ضمن السطر` وكتلة شيفرة:

```javascript
function hello() {
  console.log("Hello, World!");
}

## لماذا تستخدم Markdown؟

### 1) البساطة والسرعة
- كتابة أسرع بقواعد قليلة
- بلا حاجة لتذكر وسوم HTML المعقدة
- تركيز على المحتوى لا التنسيق

### 2) توافق واسع
- مدعوم على GitHub وGitLab وReddit وStack Overflow
- مدعوم في معظم المحررات وIDE الحديثة
- قابل للتحويل للصيَغ التي تحتاجها

### 3) متكامل مع التحكم في الإصدارات
- ملفات نصية صِرفة تعمل جيداً مع Git
- سهلة التتبع والتعاون
- بلا تعارضات ملفات ثنائية

### 4) ملائم للمستقبل
- النص الصِرف لا يقدُم
- بلا اعتماد على صيغ احتكارية
- سهل النقل بين المنصات

### 5) سهولة التعلم
- تعلم سريع (أساسيات خلال 30 دقيقة)
- صياغة متسقة عبر المنصات
- بلا متطلبات برمجية معقدة

## مناسب لأي استخدامات؟

### 📝 كتابة الوثائق
- **وثائق تقنية**: توثيق API، أدلة المستخدم، README
- **توثيق برمجي**: تعليقات الشيفرة ووثائق المشاريع
- **قواعد معرفة**: ويكي وأنظمة المساعدة والوثائق الداخلية

### ✍️ إنشاء المحتوى
- **تدوين**: مدونات شخصية وشركات ومقالات تقنية
- **كتابة أكاديمية**: أبحاث وأطروحات وتقارير
- **كتب وإلكترونيات**: كتب تقنية وروايات ومحتوى تعليمي

### 💼 تطبيقات الأعمال
- **إدارة مشاريع**: قوائم مهام وملاحظات ومحاضر اجتماعات
- **البريد الإلكتروني**: نصوص منسقة بلا تعقيد HTML
- **العروض التقديمية**: تحويل إلى شرائح
- **التقارير**: تقارير ومُلخصات وتحديثات حالة

### 🌐 تطوير مواقع
- **مولدات مواقع ساكنة**: Jekyll وHugo وGatsby وVitePress
- **أنظمة إدارة محتوى**: WordPress وGhost وContentful
- **مواقع الوثائق**: GitBook وDocusaurus وMkDocs

### 📚 التعليم
- **مواد الدورة**: محاضرات وواجبات ومناهج
- **مهام الطلاب**: مقالات وتقارير وأبحاث
- **تعلم تعاوني**: مجموعات دراسة ومراجعات أقران

### 🔧 كتابة تقنية
- **توثيق الشيفرة**: تعليقات داخلية وREADME
- **توثيق API**: أوصاف النهايات وأمثلة
- **شروحات**: إرشادات خطوة بخطوة

## كيف تستخدم Markdown

### 1) اختر محررك

**محررات عبر الإنترنت:**
- [معاينة Markdown الفورية](https://www.markdownlang.com/editor/)
- [HTML إلى Markdown](https://www.markdownlang.com/html-to-markdown/)
- [Markdown إلى HTML](https://www.markdownlang.com/markdown-to-html/)
- [URL إلى Markdown](https://www.markdownlang.com/url-to-markdown/)

**تطبيقات سطح المكتب:**
- **Typora**: محرر WYSIWYG لـ Markdown
- **Mark Text**: معاينة فورية
- **Obsidian**: تطبيق ملاحظات يدعم Markdown
- **Notion**: مساحة عمل تدعم Markdown

**محررات الشيفرة:**
- **VS Code**: إضافات Markdown
- **Sublime Text**: حِزم Markdown
- **Atom**: معاينة مضمنة
- **Vim/Neovim**: إضافات Markdown

### 2) تعلّم القواعد

#### العناوين
```markdown
# H1 عنوان
## H2 عنوان
### H3 عنوان
#### H4 عنوان
##### H5 عنوان
###### H6 عنوان

تنسيق النص

**نص عريض**
*نص مائل*
***عريض ومائل***
~~شطب~~
`شيفرة ضمن السطر`

القوائم

- عنصر غير مرتّب
- عنصر آخر
  - عنصر متداخل
  - عنصر متداخل آخر

1. عنصر مرتّب
2. عنصر آخر
   1. عنصر متداخل
   2. عنصر متداخل آخر

الروابط والصور

[Markdown Lang](https://www.markdownlang.com/)
[Markdown Lang بعنوان](https://www.markdownlang.com/ "Markdown Lang")

![نص بديل](image-url.jpg)
![صورة بعنوان](image-url.jpg "عنوان الصورة")

كتل الشيفرة

```javascript
function hello() {
  console.log("Hello, World!");
}
```

```python
def hello():
    print("Hello, World!")
```

الجداول

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 行 1 | 数据 1 | 数据 2 |
| 行 2 | 数据 3 | 数据 4 |

اقتباسات كتلية

> هذا اقتباس كتلي
> 
> يمكن أن يمتد لعدة أسطر
> 
> > ويمكن تعشيشه

3) تمرّن وجرّب

• ابدأ بمستندات بسيطة
• استخدم محرراً على الويب لمعاينة فورية
• تمرّن على عناصر الصياغة المختلفة
• جرّب التحويل إلى صيغ متعددة

كيف يعمل؟

1) عملية التحليل

تعمل Markdown عبر خطوتين:

1. التحليل: يقرأ المُحلِّل النص ويعرّف الصياغات
2. العرض: يحوّلها إلى HTML أو صيغ أخرى

2) مكوّنات المُحلِّل

المُحلِّل المعجمي (Tokenization)

• تقسيم النص إلى رموز
• التعرّف على عناصر الصياغة
• التعامل مع المحارف الخاصة وتسلسلات الهروب

المُحلِّل النحوي (بناء AST)

• إنشاء شجرة بناء مجردة (AST)
• تمثيل بنية المستند
• معالجة التعشيش والعلاقات بين العناصر

المُعرِض (توليد المخرجات)

• تحويل AST إلى الصيغة الهدف (HTML، PDF ...)
• تطبيق الأنماط وقواعد التنسيق
• معالجة الحالات الحدّية والصيغ الخاصة

3) محللات شائعة

JavaScript

• marked: سريع وخفيف
• markdown-it: قابل للإضافة ويدعم التوسعة
• remark: جزء من منظومة unified

Python

• markdown: تنفيذ كامل الميزات
• mistune: سريع وخفيف
• marko: قابل للتوسعة وسريع

لغات أخرى

• PHP: Parsedown، CommonMark
• Ruby: Redcarpet، Kramdown
• Go: goldmark، blackfriday

4) نظام التوسعات

تدعم معظم محللات Markdown التوسعات:

GitHub Flavored Markdown (GFM)

• الجداول
• الشطب
• قوائم المهام
• الروابط التلقائية
• كتل الشيفرة المحاطة

CommonMark

• مواصفة موحدة
• توافق أفضل بين المُحلّلات
• سلوك أكثر قابلية للتنبؤ

توسعات مخصّصة

• المعادلات الرياضية (KaTeX، MathJax)
• المخططات (Mermaid، PlantUML)
• الحواشي السفلية
• قوائم التعاريف
• جدول المحتويات

5) سير عمل التحويل

graph LR
    A[نص Markdown] --> B[المُحلِّل]
    B --> C[AST]
    C --> D[渲染器]
    D --> E[HTML/PDF/DOCX]
    
    F[توسعات] --> B
    G[إعداد] --> B
    H[إضافات] --> D

6) أمثلة عملية

عند الكتابة:

# Hello World

هذا نص **عريض** و*مائل*.

- عنصر 1
- عنصر 2

يحوّله المُحلِّل إلى:

<h1>Hello World</h1>
<p>هذا نص <strong>عريض</strong> و<em>مائل</em>.</p>
<ul>
<li>عنصر 1</li>
<li>عنصر 2</li>
</ul>

ابدأ الآن

هل أنت مستعد للبدء؟ إليك خطوات لاحقة:

1. اختر محرراً يناسب سير عملك
2. تمرّن على القواعد الأساسية بوثائق بسيطة
3. استكشف التوسعات مثل ميزات GFM
4. جرّب محللات مختلفة واختر الأنسب
5. أدمج Markdown في عملك اليومي للتوثيق والتدوين والملاحظات

بساطة Markdown وقوتها تجعلها خياراً ممتازاً لكل من يكتب بانتظام، سواء للتوثيق التقني أو الكتابة الإبداعية أو الملاحظات اليومية. ابدأ بالأساسيات وتدرّب باستمرار، وستصبح Markdown جزءاً محورياً من عُدّتك في الكتابة.