مرجع Markdown ومكونات MDX

يخزن Nibleaf محتوى الصفحات كسلاسل Markdown، ويعرض Markdown بنمط GitHub إلى جانب مجموعة موثقة من المكونات. عاين تغييرات المصدر قبل النشر؛ فقد تنتج صياغة MDX صحيحة نحويًا تخطيطًا غير مقصود.

Markdown القياسي

استخدم عناوين ATX (## Heading) والفقرات والتوكيد والروابط والصور والاقتباسات الكتلية والقوائم المرتبة وغير المرتبة والشيفرة المسيّجة والفواصل الموضوعية والشيفرة المضمّنة. كما تُدعم جداول Markdown بنمط GitHub وقوائم المهام والروابط التلقائية والنص المشطوب.

أضف لغة إلى كل كتلة شيفرة مسيّجة تحتوي على شيفرة:

```bash
docker compose -f docker-compose.prod.yml up -d
```

احتفظ بعنوان الصفحة في إعداداتها بدلًا من إضافة H1 آخر إلى المحتوى. ابدأ أقسام المحتوى عند H2، ولا تتخطّ مستويات العناوين بغرض التنسيق المرئي.

التنبيهات

تنتقل التنبيهات بنمط GitHub ذهابًا وإيابًا عبر المحرر المرئي:

> [!WARNING]
> Back up Postgres and object storage before an upgrade.

تتحول الأنواع المدعومة إلى note وinfo وtip وcheck وwarning وdanger. ويتحول important إلى معلومات، بينما يتحول caution إلى خطر.

المكونات الكتلية

تتعرف واجهة القارئ على مجموعات المكونات الآتية:

ضع وسوم الكتل في أسطر مستقلة، واترك سطرًا فارغًا حول عناصر Markdown الفرعية:

### Create a backup

Run the backup script and record the output files.

المكونات المضمّنة

استخدم <Tooltip tip="Plain-language definition">term</Tooltip> لتقديم تعريف موجز، واستخدم <Icon icon="star" ></Icon> لأيقونة مختارة من الواجهة. لا تستخدم تلميحًا لإرشادات إلزامية، ولا تعتمد على أيقونة وحدها لنقل المعنى.

الرياضيات والمخططات

تستخدم الرياضيات المضمّنة والكتلية محددات الدولار عبر KaTeX. وتستخدم مخططات Mermaid كتلة مسيّجة باللغة mermaid وتُعرض لدى العميل. أضف دائمًا نصًا محيطًا يوضح خلاصة المخطط؛ إذ يجب ألا يكون المخطط الموضع الوحيد الذي يحصل منه القارئ على معلومات مطلوبة.

الصياغة غير المدعومة أو المخصصة

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