صياغة Markdown الأساسية: دليل شامل مع أمثلة عملية

صياغة Markdown الأساسية هي الأساس الذي يحتاج كل مطوّر وكاتب وصانع محتوى إلى إتقانه. سواء كنت تكتب توثيقاً تقنياً، أو تُنشئ تدوينة، أو تُنسّق مشكلة على GitHub، فإن هذه العناصر الأساسية هي اللبنات التي ستعتمد عليها كل يوم.

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

العناوين

تُنظّم العناوين محتواك في تسلسل هرمي منطقي. يدعم Markdown ستة مستويات من العناوين، تُنشأ بوضع رموز # قبل النص.

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

ينتج عن ذلك كود HTML التالي:

<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>

أفضل ممارسات العناوين

أضف دائماً مسافة بين رمز # ونص العنوان. بدون المسافة، بعض المُحلّلات لن تتعرف عليه كعنوان.

✅ ## This Works
❌ ##This Doesn't

استخدم العناوين بالترتيب. لا تقفز من H2 إلى H4 — فهذا يُخلّ بالهيكل المنطقي للمستند ويؤثر سلباً على إمكانية الوصول وتحسين محركات البحث. فكّر في العناوين كجدول محتويات: يجب أن يندرج كل مستوى منطقياً تحت المستوى الذي يعلوه.

استخدم عنوان H1 واحداً فقط في الصفحة. فعنوان H1 هو عنوان صفحتك الرئيسي. كل شيء آخر يجب أن يكون H2 أو أدنى.

الفقرات وفواصل الأسطر

الفقرات هي أبسط عنصر في Markdown — فقط اكتب النص. افصل بين الفقرات بسطر فارغ.

This is the first paragraph.

This is the second paragraph.

فواصل الأسطر

هنا يقع كثير من المبتدئين في الخطأ. الضغط على Enter مرة واحدة لا يُنشئ سطراً جديداً في معظم عارضات Markdown. تحتاج إلى أحد الخيارين:

1. إنهاء السطر بمسافتين أو أكثر (ثم الضغط على Enter)
2. استخدام وسم <br> في HTML

This is the first line.
This is the second line.

Or use HTML:<br>
This starts a new line.

خطأ شائع

مجرد الضغط على Enter بين سطرين سيدمجهما في فقرة واحدة عند العرض:

Line one
Line two

سيُعرض هذا كالتالي: "Line one Line two" — سطر واحد. استخدم دائماً سطراً فارغاً لفقرة جديدة أو مسافات في نهاية السطر لإنشاء فاصل سطر داخل الفقرة نفسها.

تنسيق النص

يُسهّل Markdown عملية إبراز النص. إليك خيارات التنسيق الأساسية:

النص الغامق (Bold)

غلّف النص بنجمتين مزدوجتين أو شرطتين سفليتين مزدوجتين:

**This is bold text**
__This is also bold__

مخرجات HTML: <strong>This is bold text</strong>

النص المائل (Italic)

غلّف النص بنجمة واحدة أو شرطة سفلية واحدة:

*This is italic text*
_This is also italic_

مخرجات HTML: <em>This is italic text</em>

نص غامق ومائل معاً

ادمج ثلاث نجمات للحصول على كلا التنسيقين:

***Bold and italic***
___Also bold and italic___
**_Or mix like this_**

مخرجات HTML: <strong><em>Bold and italic</em></strong>

نص مشطوب (Strikethrough)

استخدم علامتي تلدة مزدوجتين (هذا امتداد GFM، لكنه مدعوم في كل مكان تقريباً):

~~This text is crossed out~~

مخرجات HTML: <del>This text is crossed out</del>

خطأ شائع

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

✅ This is**very**important
❌ This is__very__important

الاقتباسات

تُنشأ الاقتباسات باستخدام الرمز >. تُستخدم عادةً لاقتباس المصادر، أو تسليط الضوء على ملاحظات مهمة، أو إبراز معلومات رئيسية.

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber

مخرجات HTML:

<blockquote>
  <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
  — John Gruber</p>
</blockquote>

اقتباسات متعددة الفقرات

أضف > على السطر الفارغ بين الفقرات:

> First paragraph of the quote.
>
> Second paragraph of the quote.

اقتباسات متداخلة

استخدم >> للتداخل:

> This is the outer quote.
>
>> This is a nested quote inside it.

اقتباسات مع عناصر أخرى

يمكنك دمج الاقتباسات مع تنسيقات Markdown الأخرى:

> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.

القوائم

القوائم من أكثر عناصر Markdown استخداماً. ستصادف ثلاثة أنواع: قوائم غير مرتبة، وقوائم مرتبة، وقوائم مهام.

القوائم غير المرتبة

استخدم - أو * أو + كعلامات. اختر واحدة والتزم بها للحفاظ على التناسق:

- First item
- Second item
- Third item

مخرجات HTML:

<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ul>

القوائم المرتبة

استخدم أرقاماً متبوعة بنقطة. الأرقام الفعلية لا تهم — Markdown يرقّمها تلقائياً:

1. First step
2. Second step
3. Third step

المثير للاهتمام أن هذا ينتج نفس المخرجات:

1. First step
1. Second step
1. Third step

كلاهما يُعرض كقائمة مرقّمة صحيحة 1-2-3. لكن الممارسة المثلى هي استخدام أرقام متسلسلة لتسهيل قراءة الملف المصدري.

القوائم المتداخلة

استخدم مسافتين أو أربع مسافات للإزاحة لإنشاء قوائم فرعية:

1. Main item
   - Sub-item A
   - Sub-item B
     - Sub-sub-item
2. Another main item

قوائم المهام

قوائم المهام (ميزة من GFM) تستخدم - [ ] للعناصر غير المحددة و- [x] للعناصر المحددة:

- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish

خطأ شائع

نسيان السطر الفارغ قبل القائمة عندما تأتي بعد فقرة. بعض المُحلّلات تتطلب ذلك:

✅ Here is my list:

- Item one
- Item two

❌ Here is my list:
- Item one
- Item two

الأكواد البرمجية

عرض الأكواد البرمجية من أقوى مزايا Markdown، وإتقانه مهم جداً لسهولة القراءة.

الكود المضمّن (Inline Code)

غلّف الكود بعلامات اقتباس خلفية مفردة للعرض المضمّن:

Use the `print()` function to output text.

مخرجات HTML: Use the <code>print()</code> function to output text.

إذا كان الكود نفسه يحتوي على علامة اقتباس خلفية، استخدم علامتي اقتباس خلفيتين:

``There is a literal `backtick` here.``

كتل الأكواد (Code Blocks)

للأكواد متعددة الأسطر، استخدم ثلاث علامات اقتباس خلفية (كتل أكواد مسيّجة) مع مُعرّف لغة اختياري لتلوين الصياغة:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

مُعرّف اللغة (javascript، python، html، css، bash، إلخ) يُفعّل تلوين الصياغة في معظم العارضات. احرص دائماً على تضمينه — فهو يُحسّن سهولة القراءة بشكل كبير.

كتل الأكواد بالإزاحة

يمكنك أيضاً إنشاء كتل أكواد بإزاحة كل سطر بأربع مسافات أو علامة تبويب واحدة:

    function add(a, b) {
      return a + b;
    }

لكن كتل الأكواد المسيّجة هي المفضّلة بشدة لأنها تدعم تلوين الصياغة ولا تتطلب إزاحة كل سطر.

الروابط

الروابط ضرورية لربط المحتوى. يدعم Markdown عدة أنماط للروابط.

الروابط المضمّنة

الشكل الأكثر شيوعاً — النص بين أقواس مربعة، والرابط بين أقواس عادية:

[Visit Example](https://example.com)

مخرجات HTML: <a href="https://example.com">Visit Example</a>

روابط مع عناوين

أضف عنواناً بين علامتي تنصيص بعد الرابط (يظهر كتلميح عند التمرير):

[Visit Example](https://example.com "Example Website")

روابط بأسلوب المرجع

لنص مصدري أنظف عندما يكون لديك روابط كثيرة، استخدم أسلوب المرجع:

I use [Google][1] and [GitHub][2] daily.

[1]: https://google.com "Google"
[2]: https://github.com "GitHub"

هذا يُبقي فقراتك نظيفة ويجمع كل الروابط في الأسفل — وهو مفيد جداً في المستندات الطويلة.

الروابط التلقائية

غلّف الرابط أو البريد الإلكتروني بأقواس زاوية للربط التلقائي:

<https://example.com>
<contact@example.com>

معظم العارضات الحديثة (مثل GitHub) تربط الروابط الخام تلقائياً بدون أقواس زاوية، لكن استخدامها يضمن التوافق.

خطأ شائع

نسيان أن المسافات في الروابط تحتاج إلى ترميز. استخدم %20 بدلاً من المسافات:

✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)

الصور

الصور تستخدم نفس صياغة الروابط، لكن مع علامة تعجب ! في البداية:

![Alt text describing the image](/path/to/image.webp)

مخرجات HTML: <img src="/path/to/image.webp" alt="Alt text describing the image">

صور مع عناوين

![A sunset over the ocean](/images/sunset.webp "Beautiful sunset")

صور قابلة للنقر

ادمج صياغة الرابط والصورة لجعل الصورة قابلة للنقر:

[![Alt text](/images/photo.webp)](https://example.com)

أفضل ممارسات النص البديل

اكتب دائماً نصاً بديلاً وصفياً. فهو يخدم غرضين أساسيين:

1. إمكانية الوصول — تستخدمه قارئات الشاشة لوصف الصور للمستخدمين ضعاف البصر
2. تحسين محركات البحث — تستخدمه محركات البحث لفهم محتوى الصورة

✅ ![Markdown syntax cheat sheet showing headings, lists, and links](/images/cheatsheet.webp)
❌ ![image](/images/cheatsheet.webp)
❌ ![](/images/cheatsheet.webp)

الخطوط الأفقية

أنشئ خطاً أفقياً (فاصل موضوعي) لفصل الأقسام بصرياً. استخدم ثلاث شرطات أو أكثر، أو نجمات، أو شرطات سفلية:

---
***
___

الثلاثة جميعها تُنتج نفس كود HTML: <hr>

الممارسة المثلى: استخدم --- بشكل ثابت وأضف دائماً أسطراً فارغة قبلها وبعدها:

Content above the rule.

---

Content below the rule.

تخطّي الأحرف الخاصة

ماذا لو أردت عرض نجمة أو رمز # حرفياً دون تفعيل تنسيق Markdown؟ استخدم شرطة مائلة عكسية \ قبل الحرف:

\* This is not italic \*
\# This is not a heading
\- This is not a list item

إليك القائمة الكاملة للأحرف التي يمكنك تخطّيها:

\   Backslash
`   Backtick
*   Asterisk
_   Underscore
{}  Curly braces
[]  Square brackets
()  Parentheses
#   Hash
+   Plus sign
-   Hyphen
.   Dot
!   Exclamation mark
|   Pipe

مرجع سريع

إليك كل عناصر الصياغة الأساسية في جدول واحد للبحث السريع:

Element         Syntax              HTML
--------------  ------------------  -----------
Heading 1       # Text              <h1>
Heading 2       ## Text             <h2>
Heading 3       ### Text            <h3>
Bold            **text**            <strong>
Italic          *text*              <em>
Bold + Italic   ***text***          <strong><em>
Strikethrough   ~~text~~            <del>
Blockquote      > text              <blockquote>
Ordered list    1. item             <ol><li>
Unordered list  - item              <ul><li>
Inline code     `code`              <code>
Link            [text](url)         <a href>
Image           ![alt](src)         <img>
Horizontal rule ---                 <hr>
Line break      spaces + Enter      <br>

طبّق ما تعلّمته

الآن بعد أن تعلّمت كل عناصر صياغة Markdown الأساسية، حان وقت التطبيق. إليك ما يمكنك فعله:

1. تدرّب على الكتابة: أنشئ ملف notes.md وجرّب كل عنصر صياغة. كلما كتبت أكثر، أصبح الأمر أكثر طبيعية.

2. استخدم أداة معاينة: معاينة Markdown المدمجة في VS Code (Ctrl+Shift+V / Cmd+Shift+V) تتيح لك رؤية المخرجات المُعالجة في الوقت الفعلي أثناء الكتابة.

3. حوّل وشارك: عندما يصبح مستند Markdown جاهزاً للمشاركة، حوّله إلى مخرجات مصقولة — حوّل Markdown إلى HTML للنشر على الويب، أنشئ PDF للمستندات الجاهزة للطباعة، أو صدّره إلى Word للتحرير التعاوني.

4. استكشف المزيد: بمجرد إتقانك للصياغة الأساسية، انتقل إلى دليل صياغة Markdown المتقدمة للجداول والحواشي السفلية وقوائم التعريفات وغيرها. جديد على Markdown تماماً؟ ابدأ بـما هو Markdown للحصول على الصورة الكاملة.

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