كيف تستخدم محرر Markdown
- اكتب Markdown أو الصقه في المحرر.
- شاهد المعاينة الحية تتحدّث أثناء الكتابة، وهي تُعرض بصيغة Markdown المتوافقة مع GitHub (GFM).
- انقر نسخ HTML لنسخ HTML المولَّد لاستخدامه في موقع أو نظام إدارة محتوى أو رسالة بريد.
- أو انسخ Markdown نفسه لملف README أو مسألة (issue) أو طلب دمج أو صفحة توثيق.
يتم العرض في متصفحك، ولا يُرفع نصك ولا يُخزَّن. ويُعقَّم HTML المعروض، فتُزال النصوص البرمجية والسمات الخطرة في المحتوى الملصوق قبل إظهار المعاينة.
ما هو Markdown؟
Markdown لغة ترميز خفيفة أنشأها John Gruber عام 2004. وهي تستخدم علامات الترقيم في النص العادي للتنسيق: # للعناوين، و* أو _ للتأكيد، و- للقوائم. ويبقى المصدر مقروءًا كنص عادي، وتحوّله أداة العرض إلى HTML.
ترك الوصف الأصلي حالات حدّية كثيرة دون تعريف، فاختلفت التطبيقات فيما بينها. وCommonMark مواصفة مفصّلة تحسم هذه الالتباسات، أما Markdown المتوافق مع GitHub فهو امتداد شامل لـ CommonMark يضيف ميزات يستخدمها المطورون يوميًا:
| ميزة GFM | الصياغة |
|---|---|
| الجداول | | Name | Value | مع سطر فاصل |---|---| |
| قوائم المهام | - [ ] todo و- [x] done |
| الخط المشطوب | ~~removed~~ |
| الروابط التلقائية | عناوين URL المجرّدة مثل https://example.com تصبح روابط |
| كتل الشيفرة المسوَّرة | ثلاث علامات اقتباس عكسية، يليها اسم لغة اختياريًا |
مرجع سريع لـ Markdown
# Heading 1
## Heading 2
**bold**, *italic*, `inline code`
- Bullet item
- Nested item (indent two spaces)
1. Numbered item
[Link text](https://example.com)
> A blockquote
```python
print("fenced code with a language")
```مشكلات Markdown الشائعة وكيفية إصلاحها
العنوان لا يُعرض. تشترط CommonMark وجود مسافة بعد علامات #. فـ #Title نص عادي؛ أما # Title فهو عنوان.
الأسطر تندمج في فقرة واحدة. فاصل السطر المفرد داخل الفقرة يُعامل كمسافة. اترك سطرًا فارغًا لبدء فقرة جديدة، أو أنهِ السطر بمسافتين أو بشرطة مائلة عكسية للحصول على فاصل سطر صريح. (تعامل تعليقات GitHub فواصل الأسطر المفردة بشكل يختلف عن ملفات README، وهذا مصدر شائع للالتباس.)
القائمة أو كتلة الشيفرة تنقطع مبكرًا. يجب أن يُزاح المحتوى التابع لعنصر القائمة ليتوافق مع نص العنصر. وللشيفرة داخل قائمة، أزح الكتلة المسوَّرة كلها:
1. Install the package:
```bash
npm install example
```
2. Run it.الجدول لا يُعرض. يحتاج جدول GFM إلى سطر رأس وسطر فاصل فيه ثلاث شرطات على الأقل لكل عمود، وعادةً سطر فارغ قبله. استخدم النقطتين الرأسيتين في الفاصل (:--- و:---: و---:) لمحاذاة الأعمدة.
تنسيق غير مقصود. قد تُطلق أحرف مثل * و_ و# التنسيق. هرّبها بشرطة مائلة عكسية، مثل \*not italic\*، أو ضعها بين علامات اقتباس عكسية.
نصائح وأفضل الممارسات
- أضف دائمًا اسم لغة بعد علامات الاقتباس العكسية الافتتاحية لتحصل كتل الشيفرة على تلوين الصياغة حيثما كان مدعومًا.
- اكتب نصًا بديلًا ذا معنى للصور؛ إذ تستخدمه قارئات الشاشة ويُعرض إذا تعذّر تحميل الصورة.
- استخدم جملة واحدة في كل سطر في المستندات الطويلة؛ فـ Markdown يضمّها في فقرات، وتصبح فروق الإصدارات أنظف بكثير.
- الصق أمثلة JSON أو YAML في منسّق JSON وأداة التحقق منه أو منسّق YAML وأداة التحقق منه أولًا، لتكون كتل الشيفرة في وثائقك صالحة ومرتبة.
- إذا لصقت HTML المولَّد في صفحة ويب، فمرّره على منسّق HTML لإزاحته بشكل مرتب.
الأسئلة الشائعة
ما الفرق بين Markdown وMarkdown المتوافق مع GitHub؟
GFM امتداد شامل لـ Markdown وفق CommonMark عرّفته GitHub. وهي تضيف الجداول وقوائم المهام والخط المشطوب والروابط التلقائية الموسّعة وبعض القيود على HTML الخام. ومعظم ملفات README المكتوبة لـ GitHub تُعرض هنا بالطريقة نفسها.
هل يمكنني استخدام HTML داخل Markdown؟
نعم، يسمح Markdown بـ HTML المضمَّن. وللأمان تعقّم المعاينة المخرجات، فتُزال وسوم مثل <script> وسمات معالجات الأحداث مثل onclick وروابط javascript:.
لماذا يبدو Markdown الخاص بي مختلفًا في موقع آخر؟
تستخدم المنصات نكهات مختلفة من Markdown وأوراق أنماط خاصة بها. الصياغة الأساسية (العناوين والتأكيد والقوائم والروابط والشيفرة) متسقة، لكن الجداول وفواصل الأسطر والإضافات مثل الحواشي السفلية أو الرياضيات تختلف بين أدوات العرض.
كيف أحوّل Markdown إلى HTML؟
اكتب Markdown أو الصقه، وراجع المعاينة، ثم انقر نسخ HTML. المخرجات HTML دلالي بسيط (عناوين وفقرات وقوائم وجداول) بلا تنسيق، فيكتسب CSS الصفحة التي تلصقه فيها.
آخر تحديث