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

> استخدم Markdown وامتدادات GitHub والرياضيات والمخططات ومكونات التوثيق التي يعرضها Nibleaf ويحوّلها ذهابًا وإيابًا بأمان.

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

## Markdown القياسي

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

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

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

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

## التنبيهات

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

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

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

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

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

| المكونات | الغرض | السمات المهمة |
| --- | --- | --- |
| `Card`, `CardGroup` | وجهات مترابطة | `title` و`href` و`icon`، والسمة `cols` للمجموعة |
| `Steps`, `Step` | إجراءات مرتبة | السمة `title` للخطوة |
| `Tabs`, `Tab` | بدائل لا يمكن اختيارها معًا | السمة `title` لعلامة التبويب |
| `Accordion`, `AccordionGroup` | تفاصيل اختيارية | `title` و`defaultOpen` |
| `Frame` | وسائط مع سياق | `caption` |
| `ParamField`, `ResponseField` | أوصاف حقول API | `name` و`type` و`required` و`default` و`deprecated` |
| `CodeGroup` | عينات شيفرة بديلة | تصبح لغات الشيفرة المسيّجة تسميات |
| `Expandable`, `Update`, `Columns`, `Column`, `Banner` | محتوى منظّم تكميلي | حقول العنوان أو التسمية الخاصة بكل مكوّن |
| `FileTree`, `Folder`, `File` | رسوم توضيحية لبنية المشروع يكتبها المؤلف | `name` للملف والمجلد، و`defaultOpen` للمجلد، و`icon` للملف |
| `ApiExample`, `RequestExample`, `ResponseExample` | قراءة متجاورة للطلب والاستجابة | `title` و`status` للاستجابة |
| `RelatedContent`, `RelatedCard` | قراءات تالية في نهاية الصفحة | `title` للمجموعة والبطاقة، و`description` و`href` و`icon` للبطاقة |

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

```mdx
### Create a backup

Run the backup script and record the output files.

```

شجرة الملفات رسم توضيحي وليست متصفحًا للمستودع. يعرض Nibleaf الأسماء المكتوبة
في محتوى الصفحة فقط؛ فلا يجتاز المستودع المصدّر، ولا يقرأ ملفات البيان أو
اللقطات، ولا يجلب مسارًا، ولا يرسل طلب شبكة. وتلتزم أمثلة API والبطاقات المرتبطة
بالحد نفسه الذي يقتصر على بيانات المؤلف. تمر الروابط كذلك عبر مطهّر روابط الموقع
المنشور وآلية إعادة الكتابة.

تستخدم علامات التبويب ومجموعات الشيفرة موضع تبويب متحركًا. تنقل بالسهيمين
الأيسر والأيمن، مع عكس الاتجاه في RTL، أو بمفتاحي Home وEnd. تربط الأكورديونات
والعناصر القابلة للتوسيع والمجلدات كل زر بلوحته عبر معرّفات وصول ثابتة. وتستخدم
شجرة الملفات قوائم متداخلة بدل نمط شجرة ARIA غير مكتمل.

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

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

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

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

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

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

## قابلية النقل والترحيل

يمثل الكتالوج في `@nibleaf/shared/documentation-components` عقد التأليف البرمجي
ذا الإصدار الذي يستخدمه المحرر ومصيّر التطبيق والأرشيف الثابت ومستودعات السمات
المعتمدة على Git. مخطط الإصدار 1 إضافي، ولذلك لا تحتاج الصفحات القائمة إلى
ترحيل. يدعم `Banner` السمة `type`، بينما لا تدخل `dismissible` عمدًا في العقد
القابل للنقل. تطهّر مستودعات السمات المستقلة MDX الخام بقائمة سماح صريحة، وتفصل
مصدر السمة والمكونات الذي يملكه العميل عن ملفات البيان واللقطات التي يملكها
Nibleaf.