كتل الكود

اكتب كتلة كود مسيّجة مع لغة، فيلوّنها LaRecipe على الخادم، وتكون الألوان في HTML قبل أن يعمل أي JavaScript. وبضع كلمات بعد اللغة تضيف عنوانًا أو تميّز أسطرًا:

```php title="app/Http/Controllers/SubscribeController.php" {3}
public function __invoke(Request $request): JsonResponse|RedirectResponse
{
    $data = $request->validate([
```

اكتب اللغة دائمًا: فهي تسمّي الكتلة وتخبر الوكلاء بما يقرؤونه. وحين يكون الكود الذي تعرضه موجودًا في تطبيقك، ضمّنه من الملف بدلًا من لصقه، عبر تضمين مقتطف، فيتغيّر المثال حين يتغيّر الكود.

العناوين

يسمّي title="..." الكتلة في رأسها، وعادة باسم الملف الذي جاءت منه. ومن دون عنوان، يعرض الرأس اللغة. والصيغة [app/Models/Order.php] اختصار للأمر نفسه.

'search' => [
    'driver' => 'client',
    'budget_kb' => 300,
],

```php title="config/larecipe.php"
'search' => [
    'driver' => 'client',
    'budget_kb' => 300,
],
```

الأسطر المميّزة

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

{
  "$schema": "https://larecipe.saleem.dev/schemas/3.x/larecipe.json",
  "name": "LaRecipe",
  "versions": [
    { "id": "3.x", "default": true },
    { "id": "2.x", "status": "maintained" }
  ]
}

```json {4-5}
{
  "$schema": "https://larecipe.saleem.dev/schemas/3.x/larecipe.json",
  "name": "LaRecipe",
  "versions": [
    { "id": "3.x", "default": true },
    { "id": "2.x", "status": "maintained" }
  ]
}
```

أرقام الأسطر

يضيف showLineNumbers هامشًا بأرقام الأسطر، للأمثلة الطويلة التي يشير إليها النص برقم السطر.

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

الفروق

لتعرض تغييرًا، أضف diff بعد اللغة وابدأ كل سطر بعلامة، كما في الـ patch: + للسطر المضاف، و - للسطر المحذوف، ومسافة لبقية الأسطر. يحذف LaRecipe العلامات، ويلوّن الكود بلغته، ويعلّم كل سطر في الهامش.

'sets' => [
    'docs' => [
        'route' => ['prefix' => 'docs'],
        'route' => ['prefix' => ''],
    ],
],

```php diff
 'sets' => [
     'docs' => [
-        'route' => ['prefix' => 'docs'],
+        'route' => ['prefix' => ''],
     ],
 ],
```

تجتمع أجزاء السياج بأي ترتيب بعد اللغة: ```php title="routes/web.php" {2} showLineNumbers.

مجموعات الكود

ضع عدة كتل كود داخل CodeGroup لتعرض بدائل على شكل تبويبات فوق لوحة واحدة. ويصبح عنوان كل كتلة، أو لغتها، تسمية التبويب. راجع المكوّنات لمثال حي.

تضمين المقتطفات

أمثلة الكود التي تصف تطبيقك يجب أن تأتي من تطبيقك. وتضمين المقتطف سطر يبدأ بـ <<< ويشير إلى ملف، بدءًا من جذر مشروعك:

<<< @/resources/larecipe/extension.tsx {8}

يقرأ LaRecipe الملف حين يُصيّر الصفحة ويحوّله إلى كتلة كود، عنوانها مساره، بلغة يحدّدها امتداده. وهذا المثال حي: إنه ملف الإضافة الرئيسي لهذا الموقع، الملف الذي يسجّل نموذج النشرة البريدية في أسفل الصفحة.

import { defineExtension } from '@larecipe/ui'
import { DocsFlow } from './DocsFlow'
import { InstallTabs } from './InstallTabs'
import { Subscribe } from './Subscribe'
import './docs-flow.css'
import './install-tabs.css'
import './subscribe.css'
// Server-only components (no React): only their styles ship here.
import './byline.css'
import './featured-on.css'
import './features.css'

// Our LaRecipe extension: the React side of the components this site adds.
// Each one is also defined in PHP (AppServiceProvider) with its props, its
// server fallback and its Markdown form.
export default defineExtension({ components: { DocsFlow, InstallTabs, Subscribe } })

كل ما يأتي بعد المسار يعمل كما في السياج: تمييز الأسطر، و showLineNumbers، و diff، أو title="..." ليحلّ محلّ المسار في الرأس. وأرقام الأسطر المميّزة تُعدّ من أعلى الكود المضمَّن، لا من أعلى الملف. وحين يتغيّر الملف، تُصيَّر الصفحة من جديد عند الطلب التالي.

تضمين منطقة واحدة

معظم الملفات أطول من أن تُعرض كاملة. علّم الجزء الذي تريده بتعليق #region، وأعطه اسمًا، وضمّن تلك المنطقة وحدها:

public function refund(int $amount): Refund
{
    // #region refund
    $refund = $this->payments->refund($this->payment_id, $amount);

    $this->refunds()->save($refund);
    // #endregion

    return $refund;
}

<<< @/app/Billing/Invoice.php#refund

الكود المضمَّن هو الأسطر الواقعة بين #region refund و #endregion الخاص بها، مع حذف المسافة البادئة المشتركة. ويمكن للمناطق أن تتداخل، والعلامة تعمل في أي نمط تعليق: // و # و /* */ و <!-- --> و {{-- --}} و -- و ;. وحين تضمّن ملفًا كاملًا، يحذف LaRecipe علامات المناطق.

حين يكون المقتطف مفقودًا

الملف المنقول أو المنطقة التي تغيّر اسمها لا تفشل بصمت. تعرض الصفحة تحذير "Snippet not found" مكان الكود، ويبلّغ php artisan larecipe:validate عن خطأ مع رقم السطر، فيوقف المثالُ القديم عمليةَ CI لديك بدلًا من أن يصل إلى القارئ.

ما الذي يمكن تضمينه

@/ هو جذر المقتطفات: المسار الأساسي لمشروعك في مجموعة توثيق المستودع. وبعض الملفات لا تُضمَّن أبدًا، حتى داخل الجذر، كي لا يصبح التوثيق بابًا خلفيًا إلى إعداداتك: الملفات النقطية مثل .env، و config/، و storage/، و vendor/، والمفاتيح، وبيانات الاعتماد، وقواعد البيانات، والسجلات.

تفاصيل

التالي

• التنقل: الشريط الجانبي، من المجلدات أو من navigation.json.
• المكوّنات: الخطوات والتبويبات والبطاقات وغيرها.
• المراجع الحية: المسارات والأوامر والنماذج والأحداث مقروءة من تطبيقك، للحقائق التي لا ينبغي لصقها أبدًا.