Markdown: است��دام HTML داخل Markdown

Markdown ليس قادرًا على كل شيء — عندما تقصر الصيغة، فقط اكتب HTML مباشرة.

1. ما ستتعلمه

• القواعد الأساسية لتضمين HTML في Markdown
• الفرق بين HTML المضمن و HTML على مستوى الكتلة
• السيناريوهات الشائعة حيث يسد HTML الفجوات
• الحالات الحدية بين HTML و Markdown
• اعتبارات الأمان والتوافق

2. قصة حقيقية لمطور واجهة أمامية

(1) نقطة الألم: حدود Markdown تمنع المتطلبات

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

(2) الحل: كتابة HTML مباشرة في Markdown

أخبرها المهندس الأول توم: "يمكنك كتابة HTML داخل Markdown." استخدمت ليزا وسوم <span> مع سمة style لإنشاء تسميات ملونة. لا حاجة للقطات الشاشة، يبقى النص قابلاً للبحث، ويضيف فقط بضعة أسطر من HTML.

| حالة الاختبار | الحالة |
|:----------|:------|
| تسجيل دخول المستخدم | <span style="color: green;">✅ نجاح</span> |
| API الدفع | <span style="color: red;">❌ فشل</span> |

3. قواعد HTML في Markdown

صُمم Markdown كـ "طريقة أسهل لكتابة HTML." ونتيجة لذلك، فهو يدعم بشكل أصلي تضمين HTML في المستندات:

graph TB
    A[مستند Markdown] --> B[صيغة Markdown]
    A --> C[صيغة HTML]
    B --> D[عناوين / قوائم / جداول]
    C --> E[HTML على مستوى الكتلة]
    C --> F[HTML مضمن]
    E --> G[div / table / pre]
    F --> G[span / img / br]

graph TB
    A[مستند Markdown] --> B[صيغة Markdown]
    A --> C[صيغة HTML]
    B --> D[عناوين / قوائم / جداول]
    C --> E[HTML على مستوى الكتلة]
    C --> F[HTML مضمن]
    E --> G[div / table / pre]
    F --> G[span / img / br]

(1) HTML المضمن

هذه فقرة مع <span style="color: red;">نص أحمر</span> و
<strong>نص غامق</strong> (باستخدام وسوم HTML).

اضغط Ctrl + <br> لكسر السطر (<br> هو وسم HTML).

▶ مثال: استخدام HTML لتحقيق ما لا يستطيعه Markdown

هذا نص في Markdown العادي.

<kbd>Ctrl</kbd> + <kbd>S</kbd> لحفظ الملف.

الترقية إلى إصدار <abbr title="الإصدار 3.0">v3.0</abbr>.

(3) استخدامات HTML الشائعة على مستوى الكتلة

<!-- حاوية مخصصة -->
<div style="border: 1px solid #ddd; padding: 16px; border-radius: 8px;">
  <h3>تحديث مهم</h3>
  <p>صيانة مجدولة في نهاية هذا الأسبوع.</p>
</div>

<!-- تخطيط متعدد الأعمدة -->
<div style="display: flex; gap: 16px;">
  <div style="flex: 1;">العمود الأيسر</div>
  <div style="flex: 1;">العمود الأيمن</div>
</div>

<!-- جدول منسق -->
<table>
  <tr>
    <th style="background: #4CAF50; color: white;">الاسم</th>
    <th>السعر</th>
  </tr>
  <tr>
    <td>المنتج أ</td>
    <td>29$</td>
  </tr>
</table>

5. سيناريوهات شائعة حيث يسد HTML الفجوات

▶ مثال: HTML يقوم بما لا يستطيعه Markdown

<!-- فتح في علامة تبويب جديدة -->
<a href="https://example.com" target="_blank">افتح في نافذة جديدة</a>

<!-- حجم صورة مخصص -->
<img src="logo.png" width="150" alt="شعار" style="border-radius: 8px;">

<!-- تنسيق ضغطات المفاتيح -->
<kbd>Enter</kbd> أو <kbd>Ctrl</kbd> + <kbd>V</kbd>

<!-- مربع تنبيه بلون خلفية -->
<blockquote style="background: #fff3cd; border-left-color: #ffc107;">
  هذا مربع تنبيه منسق بشكل مخصص.
</blockquote>

6. الحدود بين HTML و Markdown

(1) Markdown داخل HTML على مستوى الكتلة عادة لا يُحلل

<div>
  **هذا النص لن يكون غامقًا** (صيغة Markdown تفشل داخل div)
  <strong>هذا النص غامق باستخدام HTML</strong>
</div>

استثناء: بعض المحللات (مثل Pandoc) تدعم تحليل Markdown داخل وسوم HTML، لكن GFM (GitHub) لا يدعم ذلك. لتكون آمنًا، استخدم صيغة HTML في جميع وسوم HTML على مستوى الكتلة.

(2) Markdown داخل HTML المضمن

<span style="color: red;">**هذا النص قد يُعرض غامقًا في بعض المحللات**</span>

▶ مثال: الخلط الآمن مقابل غير الآمن

✅ آمن:
- اكتب Markdown للنص الأساسي: **غامق**
- استخدم HTML للاحتياجات المخصصة: <span style="color: red;">أحمر</span>

❌ غير آمن:
<div style="padding: 8px;">
  **هذا الغامق لن يعمل على GitHub**
</div>

7. الأمان والتوافق

(1) لا تفعل هذا

❌ غير آمن: <script>alert('XSS')</script>
❌ غير آمن: <img src="x" onerror="alert('هجوم')">
❌ غير آمن: <iframe src="https://موقع-ضار.com"></iframe>

(2) قائمة التحقق من توافق HTML

<!-- ✅ متوافق عبر المنصات -->
<strong>غامق</strong>
<em>مائل</em>
<kbd>مفتاح</kbd>
<br>
<hr>

<!-- ⚠️ بعض المنصات لا تدعم -->
<details><summary>محتوى قابل للطي</summary>نص مخفي</details>
<mark>نص مميز</mark>

8. مثال كامل: مستند Markdown معزز بـ HTML

معاينة مستند Markdown معزز بـ HTML:

سجل تغييرات المنتج v3.2:
- مربع تنبيه أخضر: ملخص التحديثات
- جدول HTML: الوحدة / الحالة / المالك (مع حالة ملونة)
- وسوم ضغطات المفاتيح: F5 للتحديث
- كتلة تعليمات برمجية Bash: أمر التثبيت npm install my-app@latest
- رابط بريد إلكتروني: support@example.com (بروتوكول mailto)

النتيجة المتوقعة: سجل منتج يجمع ب��ن Markdown و HTML — Markdown يتعامل مع البنية القياسية، HTML يتعامل مع الألوان وتنسيق ضغطات المفاتيح والحاويات المخصصة.

❓ أسئلة شائعة

📖 ملخص

• Markdown يدعم بشكل أصلي تض��ين HTML، سواء مضمن أو على مستوى الكتلة
• HTML على مستوى الكتلة يحتاج إلى أسطر فارغة قبل وبعد؛ Markdown داخله عادة لا يُحلل
• HTML يسد فجوات: الألوان، الأبعاد، روابط التبويب الجديدة، الخلايا المدمجة، تنسيق ضغطات المفاتيح
• تجنب تضمين HTML غير آمن (<script>، معالجات الأحداث)
• ��لمزيد من HTML = توافق أسوأ عبر المنصات — استخدمه باعتدال
• 80% من المحتوى جيد مع Markdown القياسي؛ HTML للاحتياجات الخاصة فقط

📝 تمارين

1. مبتدئ: اكتب فقرة Markdown حيث تستخدم <span> لتلوين كلمة واحدة بالأحمر، وتستخدم <kbd> لعرض الاختصار "Ctrl+S".

2. متوسط: أنشئ مربع تنبيه منسق بشكل مخصص (باستخدام <div> مع لون خلفية وحدود) يحتوي على فقرة ورابط. قارن كيفية عرضه في VS Code مقابل GitHub.

3. متقدم: ابنِ جدول HTML (مع <thead> و <tbody>) يستبدل جدول Markdown، مع صف رأس منسق وخلية مدمجة في الصف الأول. ضع كلاً من جدول HTML وجدول Markdown في نفس المستند وقارن عرضهما.

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

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

من نحن