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

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

لا تدعم جميع معالجات Markdown كل عناصر الصياغة المتقدمة. قبل استخدامها، تحقق مما إذا كانت أداتك أو منصتك تدعم الميزة المحددة التي تحتاجها. الخبر الجيد: معظم المنصات الحديثة — GitHub وGitLab وVS Code ومولّدات المواقع الثابتة الشائعة — تدعم غالبية هذه الإضافات.

إذا لم تكن مرتاحاً بعد مع الأساسيات، ابدأ بـدليل صياغة Markdown الأساسية أولاً.

الجداول

تتيح لك الجداول تنظيم البيانات في صفوف وأعمدة مباشرةً في Markdown. استخدم الأنابيب (|) لفصل الأعمدة والشرطات (-) لإنشاء صف العنوان.

| Feature       | Basic Syntax | Extended Syntax |
| ------------- | ------------ | --------------- |
| Tables        | No           | Yes             |
| Footnotes     | No           | Yes             |
| Task Lists    | No           | Yes             |

يُعرض كالتالي:

Feature	Basic Syntax	Extended Syntax
Tables	No	Yes
Footnotes	No	Yes
Task Lists	No	Yes

محاذاة الأعمدة

تحكّم في محاذاة النص بإضافة نقطتين إلى صف فاصل العنوان:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More         |     More       |          More |

• :--- محاذاة لليسار (الافتراضي)
• :---: توسيط العمود
• ---: محاذاة لليمين

نصائح للجداول

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

كتل الأكواد المسوّرة

بينما تدعم الصياغة الأساسية كتل الأكواد المُزاحة، فإن كتل الأكواد المسوّرة أكثر عملية بكثير. أحِط الكود بثلاث علامات اقتباس خلفية (```) أو ثلاث تيلدات (~~~) وحدد لغة لتمييز بناء الجملة.

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
```

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

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))

اللغات المدعومة

تدعم معظم المُعالِجات عشرات معرّفات اللغات. إليك الأكثر شيوعاً:

Language        Identifier
--------------  ----------------
JavaScript      javascript / js
Python          python / py
TypeScript      typescript / ts
HTML            html
CSS             css
JSON            json
Bash            bash / sh
SQL             sql
Markdown        markdown / md

أفضل الممارسات لكتل الأكواد

• حدد اللغة دائماً — هذا يُفعّل تمييز بناء الجملة ويحسّن سهولة القراءة
• استخدم text أو plaintext عندما لا تنطبق أي لغة
• الكتل المسوّرة مفضّلة على الكتل المُزاحة لأنها تدعم التمييز ولا تتطلب إزاحة كل سطر

الحواشي

تتيح لك الحواشي إضافة ملاحظات ومراجع دون تشويش النص الرئيسي. يظهر محتوى الحاشية في أسفل الصفحة.

Markdown was created by John Gruber in 2004.[^1] It has since become
the standard for technical writing.[^2]

[^1]: John Gruber's original Markdown project is documented on
    [Daring Fireball](https://daringfireball.net/projects/markdown/).
[^2]: Markdown is used by GitHub, Stack Overflow, Reddit, and
    countless other platforms.

تُعرض أرقام المراجع كروابط فوقية في النص، مع الملاحظات الكاملة مُدرجة في أسفل المستند.

قواعد صياغة الحواشي

• تستخدم مرجع الحاشية [^identifier] — يمكن أن يكون المعرّف رقماً أو كلمة (بدون مسافات)
• يبدأ تعريف الحاشية بـ [^identifier]: متبوعاً بالمحتوى
• تتطلب الحواشي متعددة الفقرات إزاحة (أربع مسافات أو تاب واحد) للفقرات التالية
• يمكن وضع تعريفات الحواشي في أي مكان في المستند — تُعرض دائماً في الأسفل

Here's a footnote with multiple paragraphs.[^note]

[^note]: This is the first paragraph of the footnote.

    This is the second paragraph, indented with four spaces.

    You can even include code: `console.log("hello")`

معرّفات العناوين

تتيح لك معرّفات العناوين المخصصة إنشاء روابط مرساة دقيقة لأقسام محددة من مستندك. أضف المعرّف بين أقواس معقوفة بعد نص العنوان.

### My Custom Section {#custom-section}

ينتج عن ذلك:

<h3 id="custom-section">My Custom Section</h3>

الربط بمعرّفات العناوين

بمجرد أن يكون للعنوان معرّف، يمكنك الربط مباشرةً به:

Jump to [My Custom Section](#custom-section).

هذا مفيد بشكل خاص لإنشاء جدول محتويات يدوي في بداية المستندات الطويلة:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)
- [FAQ](#faq)

ملاحظة التوافق

تقوم العديد من المعالجات (بما في ذلك GitHub) بتوليد معرّفات العناوين تلقائياً من نص العنوان حتى بدون صياغة {#id}. ومع ذلك، فإن تعيين المعرّفات صراحةً يمنحك تحكماً كاملاً ويضمن سلوكاً متسقاً عبر المنصات.

قوائم التعريف

قوائم التعريف مثالية للمسارد والأسئلة الشائعة وأي محتوى تحتاج فيه إلى ربط المصطلحات بشرحها.

Markdown
: A lightweight markup language for creating formatted text
  using a plain-text editor.

HTML
: The standard markup language for documents designed to be
  displayed in a web browser.

YAML
: A human-readable data serialization language commonly used
  for configuration files.

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

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for creating formatted text
      using a plain-text editor.</dd>
  <dt>HTML</dt>
  <dd>The standard markup language for documents designed to be
      displayed in a web browser.</dd>
</dl>

تعريفات متعددة

يمكن أن يكون للمصطلح أكثر من تعريف واحد:

Markdown
: A lightweight markup language.
: A tool used by developers and writers worldwide.

ملاحظة التوافق

قوائم التعريف غير مدعومة من جميع المعالجات. GitHub Flavored Markdown لا يدعمها، لكن العديد من مولّدات المواقع الثابتة وأدوات التوثيق تدعمها.

النص المشطوب

يعرض النص المشطوب خطاً أفقياً عبر النص، مشيراً إلى محتوى محذوف أو قديم. أحِط النص بتيلدتين مزدوجتين (~~).

The project deadline is ~~Friday~~ Monday.
~~Old information~~ has been replaced with updated content.

يُعرض كالتالي:

The project deadline is Friday Monday.

مخرج HTML:

<p>The project deadline is <del>Friday</del> Monday.</p>

النص المشطوب مدعوم على نطاق واسع — إنه جزء من GitHub Flavored Markdown (GFM) ويعمل على معظم المنصات الحديثة.

قوائم المهام

قوائم المهام (تُسمى أيضاً مربعات الاختيار أو قوائم المهام) تنشئ قوائم تحقق تفاعلية. استخدم - [ ] للعناصر غير المكتملة و- [x] للعناصر المكتملة.

- [x] Research extended syntax features
- [x] Write first draft
- [x] Add code examples for each section
- [ ] Create cover image
- [ ] Proofread and edit
- [ ] Publish the article

يُعرض كالتالي:

• Research extended syntax features
• Write first draft
• Add code examples for each section
• Create cover image
• Proofread and edit
• Publish the article

حالات استخدام قوائم المهام

قوائم المهام شائعة بشكل خاص في:

• مشكلات وطلبات السحب في GitHub — تتبع تقدم عناصر العمل
• توثيق المشاريع — تحديد خطوات العملية
• ملاحظات الاجتماعات — تسجيل بنود العمل وحالتها

على منصات مثل GitHub، مربعات الاختيار هذه تفاعلية — يمكنك النقر للتبديل مباشرةً في العرض المُعالَج.

الإيموجي

هناك طريقتان لإضافة الإيموجي إلى مستندات Markdown.

النسخ واللصق

الطريقة الأبسط — انسخ إيموجي من أي مصدر والصقه مباشرةً في نصك:

That's a great idea! 🎉 Let's ship it! 🚀

يعمل هذا في كل مكان لأن الإيموجي حروف Unicode قياسية.

الأكواد المختصرة

تدعم بعض المنصات أكواد الإيموجي المختصرة — كلمات مفتاحية محاطة بنقطتين:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

الأكواد المختصرة الشائعة تشمل:

Shortcode              Emoji
---------------------  -----
:smile:                😄
:rocket:               🚀
:thumbsup:             👍
:warning:              ⚠️
:heavy_check_mark:     ✔️
:x:                    ❌
:fire:                 🔥
:star:                 ⭐

ملاحظة التوافق

تختلف أكواد الإيموجي المختصرة بين المنصات. يدعم كل من GitHub وSlack وDiscord مجموعات مختلفة. الإيموجي المنسوخ والملصق يعمل عالمياً وهو الخيار الأكثر أماناً للمستندات متعددة المنصات.

التمييز

يلفت التمييز الانتباه إلى الكلمات أو العبارات الرئيسية بمنحها خلفية ملوّنة. أحِط النص بعلامتي يساوي مزدوجتين (==).

This is ==critically important== information.

ينتج عن ذلك:

<p>This is <mark>critically important</mark> information.</p>

بديل HTML

إذا كان معالج Markdown لا يدعم صياغة ==، استخدم وسم HTML <mark> مباشرةً:

This is <mark>critically important</mark> information.

كلا الطريقتين تنتجان نفس النتيجة — نص مُميّز يبرز من المحتوى المحيط.

ملاحظة التوافق

صياغة ==highlight== غير مدعومة على نطاق واسع. تعمل في بعض المعالجات لكن ليس في GitHub Flavored Markdown. إذا كان التوافق مهماً، استخدم وسم HTML <mark>.

النص المنخفض والمرتفع

هذه العناصر ضرورية للترميز العلمي والتعبيرات الرياضية والصيغ الكيميائية.

النص المنخفض

استخدم تيلدة واحدة (~) لإحاطة النص المنخفض:

The chemical formula for water is H~2~O.
Carbon dioxide is CO~2~.

يُعرض كالتالي: H₂O وCO₂.

المكافئ في HTML:

<p>The chemical formula for water is H<sub>2</sub>O.</p>

النص المرتفع

استخدم علامة القبعة (^) لإحاطة النص المرتفع:

The equation is E = mc^2^.
This is the 3^rd^ edition.

يُعرض كالتالي: E = mc² والطبعة الـ3^rd.

المكافئ في HTML:

<p>The equation is E = mc<sup>2</sup>.</p>

بديل HTML

إذا كان معالجك لا يدعم صياغة ~ و^، استخدم وسوم HTML مباشرةً:

H<sub>2</sub>O is water.
E = mc<sup>2</sup> is Einstein's famous equation.

هذا النهج HTML يعمل في جميع معالجات Markdown تقريباً.

الربط التلقائي لعناوين URL

تقوم معظم معالجات Markdown بتحويل عناوين URL الخام تلقائياً إلى روابط قابلة للنقر دون أي صياغة خاصة:

Visit https://example.com for more information.

يُعرض كرابط قابل للنقر حتى بدون صياغة [text](url).

تعطيل الربط التلقائي

أحياناً تريد عرض URL كنص عادي دون جعله قابلاً للنقر. أحِطه بعلامات اقتباس خلفية لعرضه ككود مضمّن:

`https://example.com`

يعرض هذا URL ككود بدلاً من رابط قابل للنقر — مفيد للتوثيق حيث تشرح أنماط URL بدلاً من الربط بها.

متى تستخدم الروابط الصريحة

بينما الربط التلقائي مريح، فإن صياغة الروابط الصريحة تمنحك مزيداً من التحكم:

<!-- Automatic: shows raw URL -->
https://example.com

<!-- Explicit: shows custom text -->
[Visit our website](https://example.com)

استخدم الروابط الصريحة عندما تريد نص مرساة وصفي — إنه أفضل لسهولة القراءة وتحسين محركات البحث.

مرجع سريع

إليك جميع عناصر الصياغة المتقدمة بنظرة واحدة:

Element              Syntax                     Support
-------------------  -------------------------  --------
Table                | Col | Col |              Wide
Fenced Code Block    ``` code ```               Wide
Footnote             [^1] / [^1]: text          Moderate
Heading ID           ### Heading {#id}          Moderate
Definition List      Term / : Definition        Limited
Strikethrough        ~~text~~                   Wide
Task List            - [x] / - [ ]             Wide
Emoji (shortcode)    :emoji_name:               Varies
Highlight            ==text==                   Limited
Subscript            H~2~O                      Limited
Superscript          X^2^                       Limited
Auto URL Link        https://...                Wide

ابدأ باستخدام الصياغة المتقدمة

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

1. تحقق من منصتك: تأكد من الميزات التي يدعمها معالج Markdown لديك. GitHub وVS Code ومعظم مولّدات المواقع الثابتة تتعامل جيداً مع العناصر المدعومة على نطاق واسع.

2. استخدم بدائل HTML: للميزات ذات الدعم المحدود (التمييز، النص المنخفض، النص المرتفع)، بدائل وسوم HTML تعمل في كل مكان تقريباً.

3. تمرّن على محتوى حقيقي: جرّب إضافة جدول إلى README القادم، أو حواشي إلى مقالة المدونة القادمة، أو قوائم مهام إلى خطة المشروع القادمة.

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

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