ورقة مرجعية سريعة لـ Markdown

خطوة 1 / 3 33%

اختر موضوعًا في Markdown

ابدأ بمجموعة واحدة من الأمثلة، ثم افتح المرجع الكامل.

صياغة Markdown الأساسية مصنفة حسب الموضوع، مع عرض المصدر الجاهز للنسخ بجانب نتيجة محلل فعلي. تشمل أساسيات CommonMark (العناوين والقوائم والتوكيد والروابط والصور وكتل الكود المسيجة) وامتدادات GitHub Flavored Markdown (الجداول وقوائم المهام والشطب وإنشاء الروابط تلقائيًا لعناوين URL العادية). احتفظ بها بالقرب منك عند العمل في GitHub وGitLab وObsidian وأدوات إنشاء المواقع الثابتة.

كيفية استخدام الورقة المرجعية

  1. 1

    تصفَّح حسب الفئة

    انتقل إلى العناوين أو القوائم أو الكود أو الروابط أو الجداول أو امتدادات GFM.

  2. 2

    قارن المصدر بالنتيجة

    يعرض كل مثال نص Markdown الخام بجانب نتيجة محلل GFM فعلي.

  3. 3

    انسخ المقتطف

    اضغط على «نسخ» للحصول على مصدر أي مثال.

  4. 4

    راجع شارة الصياغة

    يحمل كل مثال شارة CommonMark أو GitHub Flavored Markdown (GFM).

العناوين

# عنوان H1
## قسم H2
### قسم فرعي H3

استخدم نمط ATX (#) بدلًا من Setext (=== تحت النص). تدعم جميع المُحلِّلات كلا النمطين، لكن ATX أسهل في القراءة عند مقارنة الفروق (diff).

التوكيد

*مائل* أو _مائل_، **عريض** أو __عريض__، ***عريض مائل***. يضيف GFM ~~يتوسطه خط~~.

القوائم

تستخدم القوائم غير المرتبة - أو * أو + (اختر واحدًا والتزم به):

- الأول
- الثاني
  - متداخل (مسافتان)

تُعاد ترقيم القوائم المرتبة تلقائيًا:

1. عنصر
1. عنصر
1. عنصر

الكود

مضمَّن: `code`. كتل مُسيَّجة مع وسم لغة اختياري:

```python
def hello(name):
    return f"Hello, {name}"
```

إذا كنت تفضّل الصياغة القديمة، فأزِح كتلة الكود بأربع مسافات.

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

[نص الرابط](https://example.com)
[رابط مع عنوان](https://example.com "تلميح")
![نص بديل](/path/to/image.png)

يُبقي النمط المرجعي الروابط الطويلة خارج الفقرة:

راجع [الوثائق][1].

[1]: https://example.com/docs

الجداول (GFM)

| Col A | Col B |
|-------|------:|
| a     |     1 |
| b     |    22 |

تُضبط المحاذاة بالنقطتين الرأسيتين في صف الفصل: :--- إلى اليسار، :---: في المنتصف، ---: إلى اليمين.

قوائم المهام (GFM)

- [x] تم
- [ ] مطلوب

أخطاء شائعة

  • مسافتان في نهاية السطر تُدرجان فاصل سطر داخل الفقرة، بينما تكتفي المسافة الواحدة بربط السطرين.
  • يلزم سطر فارغ قبل معظم عناصر الكتل (العناوين، القوائم، كتل الكود).
  • لا تُزِح علامات القوائم بمفتاح Tab إذا كان العارض يتوقّع مسافات؛ استخدم مسافتين أو أربع مسافات.
  • الهروب بالشرطة المائلة العكسية لإظهار علامات الترقيم حرفيًا: \*ليس مائلًا\*.
  • علامات الاقتباس الذكية تختلف باختلاف العارض: يتركها GitHub كما هي، بينما يحوّلها Pandoc.

الأسئلة الشائعة

يحدد CommonMark الأساس القابل للنقل، بما فيه العناوين والقوائم والروابط وكتل الكود المسيجة ذات سطر المعلومات الاختياري. ويضيف GFM الجداول وقوائم المهام والشطب وإنشاء الروابط تلقائيًا لعناوين URL العادية. قد تطبق المحررات الأخرى جزءًا من الصياغة أو تضيف امتدادات خاصة بها.

يعامل Markdown السطر الجديد المفرد كمسافة. للحصول على <br>، أنهِ السطر بمسافتين في نهايته، أو استخدم \ في نهاية السطر ضمن GFM.

نعم في معظم المُحلِّلات، إذ تُمرَّر وسوم HTML على مستوى الكتل دون تغيير. لكن بعض العارضات تُنقّيها (مثلًا، يزيل GitHub النصوص البرمجية المضمَّنة وسمات الأحداث).

لا يحتوي CommonMark على صياغة مدمجة لجدول المحتويات. ينشئ GitHub مراسي للعناوين ويعرض مخططًا للملفات التي تحتوي على عدة عناوين. للمنصات الأخرى قواعدها: يمكن أن يستخدم MkDocs الرمز [TOC] عند تفعيل الامتداد المناسب، بينما ينشئ Docusaurus جدول محتويات الصفحة من العناوين.

قواعد CommonMark وGFM تعمل. لكن Obsidian يضيف روابط ويكي ([[اسم الصفحة]]) ومربعات تنبيه (callout) وكتلًا مُضمَّنة خاصة به وحده، وهذه العناصر ليست ضمن هذه الورقة المرجعية.

أدوات ذات صلة