---
title: Markdown
description: 'اكتب الصفحات بصيغة Markdown بنكهة GitHub، واربط بينها بمسارات .md نسبية، وأضف التنبيهات والمكوّنات حيث لا تكفي Markdown وحدها.'
url: 'https://larecipe.saleem.dev/ar/3.x/writing/markdown'
version: 3.x
locale: ar
last_updated: '2026-10-18'
---

> Docs index: https://larecipe.saleem.dev/3.x/llms.txt · MCP: https://larecipe.saleem.dev/mcp · Skill: https://larecipe.saleem.dev/skill.md

# Markdown

الصفحة ملف Markdown تعلوه كتلة قصيرة بصيغة YAML هي ترويسة الصفحة (frontmatter). اكتب Markdown بنكهة GitHub التي تعرفها، واربط بالصفحات الأخرى بمسارات `.md` نسبية، فيُقرأ الملف نفسه جيدًا على GitHub وعلى موقعك.

```markdown
---
title: Webhooks
description: Receive signed events from the app and verify them.
sources: ["app/Webhooks/**", "routes/webhooks.php"]
---

# Webhooks

Every event is signed. Verify the signature before you trust the payload.
See [installation](../get-started/installation.md) for the setup.
```

تشرح صفحة [بنية المشروع](https://larecipe.saleem.dev/ar/3.x/get-started/project-structure.md) المفاتيح الثلاثة التي تحتاجها كل صفحة في ترويستها، وأين يوضع الملف.

## الروابط

اربط بالصفحات الأخرى بمسارات `.md` نسبية، كما تفعل على GitHub:

```markdown
See [webhook retries](./webhooks.md#retries), or go back to [installation](../get-started/installation.md).
```

يحوّل LaRecipe كل رابط إلى رابط القارئ في الإصدار واللغة نفسيهما. ويبلّغ `php artisan larecipe:validate` عن الروابط التي تشير إلى صفحات أو مراسٍ غير موجودة، ويقترح أقرب تطابق إصلاحًا لها.

## العناوين والمراسي

يحصل كل عنوان على معرّف (id): نصّه بأحرف صغيرة، مع حذف علامات الترقيم وتحويل المسافات إلى شرطات. فالعنوان `## Retry failed deliveries` يصبح `#retry-failed-deliveries`. ولكي يبقى المعرّف ثابتًا حين تعيد صياغة العنوان، حدّده بنفسك:

```markdown
## Retry failed deliveries {#retries}
```

تبني عناوين H2 و H3 جدول المحتويات، وتقسم الصفحة إلى سجلات بحث، فاجعل لكل قسم عنوانًا خاصًا به بدلًا من سطر بخط عريض.

## الصور والملفات

ضع الصور بجوار الصفحة، أو في مجلد `_assets` الخاص بالإصدار، واربط بها بمسار نسبي:

```markdown
![The review queue](./_assets/review-queue.png)
```

ولتضيف تعليقًا تحت الصورة، ضعها داخل [Frame](https://larecipe.saleem.dev/ar/3.x/writing/components.md#frame).

## التنبيهات

تُصيَّر صيغة التنبيهات في GitHub على شكل صندوق تنبيه (callout). وهي أكثر طرق كتابته قابلية للنقل: يعرضها GitHub، ويقرؤها الوكلاء، وينسّقها LaRecipe.

> [!TIP]
> **فضّل التنبيهات في الحالات البسيطة**
> تُقرأ بالشكل نفسه في محرّرك، وعلى GitHub، وعلى موقعك.

```markdown
> [!TIP] Prefer alerts for simple callouts
> They read the same in your editor, on GitHub and on your site.
```

الأنواع هي `NOTE` و `TIP` و `IMPORTANT` و `WARNING` و `CAUTION`. والنص الذي يلي العلامة في السطر الأول يصبح العنوان.

## المكوّنات

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

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

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

المحتوى داخل المكوّن Markdown. والخصائص (props) نصوص بين علامتي تنصيص. والوسم غير المعروف يُصيَّر نصًا مهرّبًا ويُفشل `larecipe:validate`. وتعرض [صفحة المكوّنات](https://larecipe.saleem.dev/ar/3.x/writing/components.md) كل مكوّن مدمج، بأمثلة حية.

### التوجيهات

لكل مكوّن أيضًا صيغة توجيه (directive) تبدأ بـ `:::`. والتوجيه والوسم ينتجان الصفحة نفسها.

**اكتب المكوّنات على شكل توجيهات**

```markdown
:::warning Before you deploy
Run `php artisan optimize` so the first reader never waits.
:::

::::tabs {sync=package-manager}
:::tab npm
`npm install`
:::
:::tab pnpm
`pnpm install`
:::
::::
```

- `:::note` و `:::tip` و `:::important` و `:::warning` و `:::caution` و `:::danger` صناديق تنبيه. وأي اسم آخر مكوّن: `:::code-group` هو `CodeGroup`.
- النص الذي يلي الاسم يملأ الخاصية `title` (و `label` في التبويب). والخصائص الأخرى توضع بين قوسين معقوفين: `{type=warning}`.
- لتداخل التوجيهات، أعطِ التوجيه الخارجي سياجًا أطول (`::::`). وسياج الإغلاق يغلق أعمق توجيه يستطيع إغلاقه.

## HTML الخام

يُهرَّب HTML الخام: فالوسم `<div>` أو `<details>` في الصفحة يظهر نصًا، ولا يُعرض وسومًا أبدًا. استخدم مكوّنًا بدلًا منه ([Accordion](https://larecipe.saleem.dev/ar/3.x/writing/components.md#accordion-and-accordiongroup) بدلًا من `<details>`، و[Frame](https://larecipe.saleem.dev/ar/3.x/writing/components.md#frame) بدلًا من figure)، أو [ابنِ مكوّنك الخاص](https://larecipe.saleem.dev/ar/3.x/customize/custom-components.md).

**اسمح بـ HTML الخام في مجموعة مستودع**

يمكن لمجموعة مستودع تحتاج صفحاتها إلى HTML خام أن تسمح به عبر `html_input` في مدخلها داخل `config/larecipe.php`:

```php title="config/larecipe.php"
'sets' => [
    'docs' => [
        // route, source and access as usual
        'html_input' => 'allow',
    ],
],
```

عندئذ يمرّ HTML الخام كما كُتب، ما عدا الوسوم التي يرشّحها GitHub، مثل `<script>` و `<iframe>` و `<style>`، فتبقى مهرّبة. وصفحات هذه المجموعة تُراجَع في git مع الكود، فالقرار لك.

أما مجموعة قاعدة البيانات فتهرّب HTML الخام دائمًا، وتمرّر كل صفحة أيضًا عبر منقّح HTML، فلا أثر لـ `html_input` فيها. راجع [مصدر قاعدة البيانات](https://larecipe.saleem.dev/ar/3.x/sources/database.md).

كان LaRecipe 2 يُصرّف Blade داخل Markdown. أما الإصدار 3 فلا ينفّذ Blade ولا PHP في أي صفحة أبدًا، مهما كان المصدر.

## تفاصيل

**كل ميزات Markdown**

يحلّل LaRecipe صيغة Markdown بمكتبة league/commonmark، مع هذه الإضافات في كل صفحة:

| الميزة | كيف تكتبها |
| --- | --- |
| الجداول، وقوائم المهام، والنص المشطوب، والروابط التلقائية | Markdown بنكهة GitHub، كما على GitHub |
| الحواشي | `A claim.[^1]` ثم لاحقًا `[^1]: The source.` |
| قوائم التعريف | المصطلح في سطر، ثم `: its definition` في السطر التالي |
| كتل الكود | كود مسيّج مع لغة. راجع [كتل الكود](https://larecipe.saleem.dev/ar/3.x/writing/code-blocks.md) |
| الرياضيات | كتلة `$$`، تُصيَّر معادلةً. راجع [المكوّنات](https://larecipe.saleem.dev/ar/3.x/writing/components.md#math) |
| المخططات | سياج ```` ```mermaid ````. راجع [المكوّنات](https://larecipe.saleem.dev/ar/3.x/writing/components.md#mermaid) |

**العناوين وأول عنوان في الصفحة**

يأتي عنوان الصفحة من `title` في ترويسة الصفحة. ومن دونه يأخذ LaRecipe أول `# Heading` في المتن، وإن لم يجده، يصنع عنوانًا من اسم الملف (فيصبح `index` هو "Introduction").

يعرض رأس الصفحة العنوان أصلًا، فلا يتكرر عنوان `# Heading` الأول داخل المقالة. ومع ذلك أبقِه: فبه يُقرأ الملف جيدًا على GitHub وفي محرّرك.

وإن لم تكن ترويسة الصفحة YAML صالحة، تظل الصفحة تُصيَّر، بترويسة فارغة، ويخبرك `php artisan larecipe:validate` بما عليك إصلاحه.

**كيف تُصنع معرّفات العناوين**

تحتفظ العربية والكتابات الأخرى بحروفها في المعرّف. وحين يتشارك عنوانان المعرّف نفسه، يحصل الثاني على `-1`، والثالث على `-2`. والسمتان `{#id}` و `{.class}` هما الوحيدتان اللتان يقبلهما LaRecipe، على العناوين والكتل الأخرى. وأي سمة أخرى، مثل `onclick`، تُتجاهل.

**كيف تُحلّ الروابط**

- الرابط النسبي يُحلّ من مجلد الصفحة التي تحويه.
- الرابط الذي يبدأ بـ `/` وينتهي بـ `.md` يُحلّ من جذر الإصدار الحالي: فالرابط `[install](/get-started/installation.md)` يصل إلى الصفحة نفسها من أي مكان في الإصدار.
- الرابط الجذري الذي يذكر إصدارًا صراحة، بعد بادئة المجموعة ولغة اختيارية، يصل إلى تلك الصفحة: `/3.x/index.md` هي الصفحة الرئيسية للإصدار 3.x، و `/ar/3.x/index.md` هي نسختها العربية. ويتحقق `larecipe:validate` من هذه الروابط بالطريقة نفسها.
- الروابط التي تحمل مخططًا (`https://` و `mailto:`) والمراسي `#anchors` تُترك كما هي. ولتربط برابط ينتهي بـ `.md` وليس من صفحاتك، اكتب الرابط كاملًا.
- تُحذف روابط `javascript:` وغيرها من الروابط غير الآمنة.
- في نسخة Markdown التي يقرؤها الوكلاء، تشير الروابط إلى الصفحات الأخرى إلى نسخ `.md` المقابلة لها، بروابط مطلقة.

يمكن للمحتوى المكتوب لـ LaRecipe 2 أن يحتفظ بـ `{{version}}` في الرابط: إذ يُستبدل بالإصدار الحالي، في الروابط وفي خصائص المكوّنات مثل `href` و `src`. أما الصفحات الجديدة فلتستخدم الروابط النسبية.

**أين يبحث LaRecipe عن الصور**

يحلّ LaRecipe مسار الصورة من مجلد الصفحة، ويبحث عن الملف في مجلد الإصدار، ثم في مجلد `_assets` الخاص بالإصدار، ثم في مجلد `_assets` في جذر التوثيق. ويقدّم الملف من `/_assets/{version}/...` تحت بادئة المجموعة. والمسار الذي يبدأ بـ `/` يُحلّ من جذر الإصدار بالطريقة نفسها. أما الصورة الموجودة في أي مكان آخر، مثل مجلد `public/` في تطبيقك أو شبكة CDN، فاكتب رابطها كاملًا مع المخطط.

**صيغة المكوّنات كاملة**

- المكوّن الذي له محتوى يُفتح بـ `<Name>` ويُغلق بـ `</Name>`. ومن دون محتوى يغلق نفسه: `<Name prop="value" />`. والمكوّن ذو المحتوى القصير يمكن أن يأتي في سطر واحد، مثل الشارة.
- تعمل القوائم وكتل الكود والمكوّنات الأخرى داخل المكوّن.
- الخاصية المجرّدة (`open`) تعني true، و `prop="false"` تعني false، و JSON يوضع بين قوسين معقوفين: `cols={3}`. ولا توجد تعبيرات JSX: لا ينفّذ LaRecipe أبدًا كودًا من توثيقك.
- المكوّنات غير المعروفة والخصائص الناقصة أو غير الصالحة تُفشل `php artisan larecipe:validate`.

**ملاحظات للكاتب التالي**

تُحذف تعليقات HTML من الصفحة، ومن نسخة Markdown المقابلة لها، ومن البحث، فيبقى `<!-- a note for the next writer -->` في المصدر وحده. أما داخل الكود المضمّن في السطر وكتل الكود، فتبقى التعليقات كما كُتبت.

يسحب سطر مثل `<<< @/app/Billing/Invoice.php#refund` الكود مباشرة من تطبيقك إلى كتلة كود، فلا يمكن للمثال أن يبتعد عن الكود: راجع [كتل الكود](https://larecipe.saleem.dev/ar/3.x/writing/code-blocks.md#snippet-includes). ولكل صفحة أيضًا نسخة Markdown للوكلاء، تُصيَّر من الصفحة المحلَّلة نفسها: راجع [واجهات الوكلاء](https://larecipe.saleem.dev/ar/3.x/agents/surfaces.md).

## التالي

- [المكوّنات](https://larecipe.saleem.dev/ar/3.x/writing/components.md): كل مكوّن مدمج، مع مثال حي.
- [كتل الكود](https://larecipe.saleem.dev/ar/3.x/writing/code-blocks.md): العناوين، وتمييز الأسطر، والفروق، وتضمين المقتطفات.
- [مرجع ترويسة الصفحة](https://larecipe.saleem.dev/ar/3.x/reference/frontmatter.md): كل مفتاح يمكن للصفحة أن تحدّده.