المكوّنات

تغطّي المكوّنات ما لا تستطيعه Markdown العادية: الخطوات، والتبويبات، والبطاقات، والفيديو. اكتب المكوّن على شكل وسم بصيغة PascalCase في سطر مستقل، مع سطر فارغ قبله وبعده. والمحتوى داخله Markdown.

<Callout type="warning" title="Before you deploy">
Run `php artisan optimize` so the first reader never waits.
</Callout>

يُصيَّر كل مكوّن أيضًا HTML عاديًا للقرّاء من دون JavaScript، و Markdown قابلًا للنقل في نسخة Markdown الخاصة بالصفحة للوكلاء. ويسرد مرجع المكوّنات الخصائص (props) لكل مكوّن، وكلا الشكلين.

كيف تكتب مكوّنًا

• المكوّن الذي لا محتوى له يغلق نفسه: <Video ... />. والمكوّن القصير يمكن أن يأتي في سطر واحد: <Badge tone="success">Stable</Badge>.
• الخصائص نصوص بين علامتي تنصيص. والخاصية المجرّدة تعني true، و JSON يوضع بين قوسين معقوفين (cols={3}).
• لكل مكوّن أيضًا صيغة توجيه تبدأ بـ :::، موصوفة في Markdown.
• الوسم غير المعروف، أو خطأ إملائي مثل <Calout>، يُصيَّر نصًا مهرّبًا. ويبلّغ عنه php artisan larecipe:validate بالرمز components.unknown، وعن الخاصية الناقصة أو غير الصالحة بالرمز components.props.
• يتجاهل المكوّن المدمج الخصائص التي لا يعلنها، فلا أثر لخاصية مكتوبة خطأً. راجع المرجع للأسماء الدقيقة.

Callout

ملاحظة أو نصيحة أو تحذير منفصل عن النص. قيمة type هي note أو tip أو important أو warning أو caution أو danger (وتعمل info و success أيضًا). والخاصية الاختيارية title تحلّ محلّ التسمية.

<Callout type="warning" title="Before you deploy">
Run `php artisan optimize` so the first reader after a deploy never waits for a page to render.
</Callout>

ينتج تنبيه GitHub المكوّن نفسه، ويُقرأ جيدًا على GitHub أيضًا:

> [!NOTE]
> Alerts and callout tags produce the same component.

Steps

إجراء مرقّم. تحتاج كل Step إلى title، ومحتواها Markdown، بما فيه كتل الكود.

1. أضف الحزمة

   composer require larecipe/larecipe

2. شغّل المثبّت

   php artisan larecipe:install

3. افتح التوثيق

   زر /docs. صفحة المقدمة موجودة هناك أصلًا.

<Steps>

<Step title="Require the package">

```bash
composer require larecipe/larecipe
```

</Step>

<Step title="Run the installer">

```bash
php artisan larecipe:install
```

</Step>

<Step title="Open your docs">
Visit `/docs`. Your Introduction page is already there.
</Step>

</Steps>

Tabs

المعلومة نفسها في بدائل يختار القارئ منها: مدير حزم، أو إطار عمل، أو مشغّل مصدر. يحتاج كل Tab إلى label. ويختار default التبويب الذي يظهر أولًا، والتبويبات التي تتشارك مفتاح sync تتبدّل معًا في الصفحة كلها.

php artisan larecipe:install --driver=repository

php artisan larecipe:install --driver=database

<Tabs sync="driver">

<Tab label="Repository">
Docs live in `docs/` as Markdown, in the same pull request as the code.

```bash
php artisan larecipe:install --driver=repository
```

</Tab>

<Tab label="Database">
Docs live in your database and change through docs migrations.

```bash
php artisan larecipe:install --driver=database
```

</Tab>

</Tabs>

من دون JavaScript تظهر كل اللوحات بالترتيب، كلٌّ تحت تسميته، فلا شيء يُخفى عن القارئ ولا عن محرّكات الزحف.

CodeGroup

عدة كتل كود تنتمي إلى بعضها، تُعرض تبويباتٍ فوق لوحة كود واحدة. ويصبح عنوان كل كتلة، أو لغتها، تسمية التبويب.

php artisan larecipe:upgrade

php artisan larecipe:upgrade --apply

<CodeGroup>

```bash title="Dry run"
php artisan larecipe:upgrade
```

```bash title="Apply"
php artisan larecipe:upgrade --apply
```

</CodeGroup>

Card و CardGroup

كتلة مرتبطة برابط، لها عنوان ووصف قصير. تأخذ href رابط .md نسبيًا، وتأخذ icon اسم أيقونة من Lucide. ويرتّب CardGroup البطاقات في أعمدة (cols، والقيمة الافتراضية 2).

<CardGroup cols="2">

<Card title="Installation" href="../get-started/installation.md" icon="rocket">
From `composer require` to a working docs site, with every installer flag.
</Card>

<Card title="Components reference" href="../reference/components.md" icon="book-open">
Every prop of every built-in component.
</Card>

</CardGroup>

البطاقة التي لا href لها كتلة ذات عنوان. ويسرد مرجع المكوّنات أسماء الأيقونات التي يمكن للبطاقة أن تستخدمها.

Columns

محتوى جنبًا إلى جنب على الشاشات العريضة، ومكدّس على الضيّقة. تصبح كل كتلة داخله عمودًا: فقرة، أو بطاقة، أو كتلة كود. والقيمة الافتراضية لـ cols هي 2.

<Columns cols="2">

**For people.** A fast site that reads well with or without JavaScript, in light and dark.

**For agents.** The same page as Markdown, plus `llms.txt`, `skill.md` and MCP.

</Columns>

Accordion و AccordionGroup

أقسام قابلة للطيّ لتفاصيل يستطيع معظم القرّاء تخطّيها. يحتاج كل Accordion إلى title، وتجعله open يبدأ مفتوحًا. ويُبقي AccordionGroup مجموعة متتالية منها معًا. ويقرأ الوكلاء المحتوى دائمًا، مفتوحًا.

<AccordionGroup>

<Accordion title="Does LaRecipe need Node on my server?">
No. The reader UI ships prebuilt inside the package. Node is needed only to build your own React components, on your machine or in CI.
</Accordion>

<Accordion title="Can my docs stay in my repository?" open>
Yes, that is the default and the recommended source. The database source is there for teams who want an admin UI.
</Accordion>

</AccordionGroup>

Badge

تسمية حالة قصيرة. قيمة tone هي neutral أو info (الافتراضية) أو success أو warning أو danger. اكتبها في سطر واحد.

مستقر

تجريبي

<Badge tone="success">Stable</Badge>

<Badge tone="warning">Beta</Badge>

Button

رابط بشكل زر، للإجراء الوحيد الذي تقود إليه الصفحة. قيمة variant هي primary (الافتراضية) أو secondary أو outline أو ghost. استخدمه باعتدال: فالصفحة التي فيها عدة أزرار لا إجراء رئيسيًا لها. ومن دون href يُصيَّر تسمية ثابتة، كما كانت أزرار العرض في LaRecipe 2.

<Button href="../get-started/installation.md" variant="outline">Install LaRecipe</Button>

FileTree

بنية مجلد، تُكتب قائمة Markdown متداخلة داخل الوسم. وتنتهي المجلدات بشرطة مائلة عُرفًا.

<FileTree>

- docs/
  - larecipe.json
  - 3.x/
    - navigation.json
    - index.md
    - get-started/
      - installation.md

</FileTree>

Frame

تعليق لوسائط، عادة لقطة شاشة أو مخطط. وتجعل الإطارات صورتها قابلة للتكبير في المتصفح. ويمكن أن يكون المحتوى أي Markdown: صورة، أو جدولًا، أو كتلة كود.

composer require larecipe/larecipe
php artisan larecipe:install

<Frame caption="The two commands that install LaRecipe.">

```bash
composer require larecipe/larecipe
php artisan larecipe:install
```

</Frame>

للقطة الشاشة، ضع الصورة داخله: ![The review queue](./_assets/review-queue.png) بين الوسمين، مع الملف بجوار الصفحة أو في مجلد _assets الخاص بالإصدار.

Video

فيديو لا يُحمَّل إلا حين يطلبه القارئ. تأخذ src ملف فيديو، أو رابطًا من YouTube أو Vimeo أو Loom، وتملأ poster و title و duration الإطار وتعليقه. ويظهر الفيديو المستضاف رابطًا مثل "شاهد على YouTube" حتى يشغّله القارئ، فلا يُحمَّل شيء من طرف ثالث مع الصفحة.

ما دام التسجيل غير موجود، اترك src. عندئذ يقول الإطار ما الذي سيأتي: نص placeholder الذي كتبته، أو "العرض المصوّر قريبًا" بلغة الصفحة. ويظل php artisan larecipe:validate يذكّرك بتحذير media.placeholder.

<Video placeholder="An example placeholder: this frame stays until the recording exists" />

<Video src="https://www.youtube.com/watch?v=VIDEO_ID" title="LaRecipe in two minutes" duration="2:40" />

Mermaid

مخطط من نص. اكتب سياج ```mermaid، أو الوسم <Mermaid> مع المصدر نفسه داخله. ويُصيَّر المخطط بألوان المظهر حين يقترب من منطقة العرض أثناء التمرير.

flowchart LR
  Code[غيّر الكود] --> Agent[يحدّث الوكيل التوثيق]
  Agent --> Review[تراجع أنت الـ pull request]
  Review --> Readers[يحصل كل قارئ على الصفحة الحالية]

```mermaid
flowchart LR
  Code[Change the code] --> Agent[Agent updates the docs]
  Agent --> Review[You review the pull request]
  Review --> Readers[Every reader gets the current page]
```

Math

معادلة بصيغة TeX. اكتب كتلة $$، أو الوسم <Math>. وتُنضَّد المعادلة في المتصفح.

$$
e^{i\pi} + 1 = 0
$$

المراجع الحية وكتل الصلاحيات

عائلتان أخريان تستخدمان صيغة الوسوم نفسها. المراجع الحية (<Route> و <Artisan> و <Model> و <Event>) تقرأ الحقائق من تطبيقك العامل، فلا يمكن أن تصبح قديمة: راجع المراجع الحية. وكتل الصلاحيات (<Can> و <Cannot>) لا تُظهر القسم إلا للقرّاء الذين تسمح لهم بواباتك (gates): راجع كتل الصلاحيات.

التالي

• كتل الكود: العناوين، وتمييز الأسطر، والفروق، وأمثلة من الكود الخاص بك.
• مرجع المكوّنات: كل خاصية، وما يُصيَّر به كل مكوّن في HTML و Markdown.
• مكوّنات React المخصّصة: أضف مكوّناتك الخاصة.