أساسيات الإعداد

معظم التطبيقات لا تغيّر شيئًا في البداية: يعيش التوثيق في docs/، ويُقدَّم على /docs، ويحق لأي أحد قراءته. وحين تريد غير ذلك، انشر ملف الإعدادات:

bash

php artisan vendor:publish --tag=larecipe-config

ثم عدّل مدخل مجموعة التوثيق في config/larecipe.php. وهذه هي الإعدادات الثلاثة التي تمسّها معظم التطبيقات:

config/larecipe.php

'sets' => [
    'docs' => [
        'route' => ['prefix' => 'docs', 'domain' => null, 'middleware' => ['web']],
        'source' => ['driver' => 'repository', 'path' => base_path('docs')],
        'access' => ['mode' => 'public'],
    ],
],

الإعداد	ما الذي يحدّده	القيم
`route.prefix`	الرابط الذي يعيش تحته التوثيق	`docs` افتراضيًا (`LARECIPE_PREFIX`). والقيمة `''` تضع التوثيق في جذر النطاق.
`source.driver`	أين تُحفظ الصفحات	`repository` (ملفات Markdown في مستودعك، وهو الموصى به) أو `database`
`access.mode`	من يحق له القراءة	`public` (الجميع)، أو `auth` (كل من سجّل دخوله)، أو `gate` (البوابة `viewLarecipe` لديك)

يدمج Laravel ملفك فوق القيم الافتراضية للحزمة، مفتاحًا علويًا بعد آخر، فيحتفظ أي مفتاح لا تكتبه بقيمته الافتراضية.

الإعدادات والمحتوى منفصلان

يحدّد config/larecipe.php كيف يقدّم تطبيقك التوثيق. أما ما يقوله التوثيق وشكله فينتقلان مع المحتوى، بجوار الصفحات:

الملف	ما يحويه
`config/larecipe.php`	مجموعات التوثيق، والمسارات، والمصدر، والوصول، ووضع المراجعة، والتخزين المؤقت، والبحث، و MCP، وواجهات الوكلاء، والذكاء الاصطناعي
`docs/larecipe.json`	الاسم، والشعار، والمظهر، والإصدارات، واللغات، وشريط التنقل العلوي، وإعادات التوجيه، والتحليلات. راجع مرجع ملف التعريف.
`navigation.json`	الشريط الجانبي لإصدار واحد. راجع التنقل.
ترويسة الصفحة (frontmatter)	عنوان صفحة واحدة، ووصفها، ومصادرها، وما شابه. راجع بنية المشروع.

وبهذا يستطيع وكيل البرمجة أن يعدّل التوثيق من دون أن يمسّ إعداداتك. والأسرار لا مكان لها في أيٍّ منهما: مفتاح المزوّد مكانه .env، ويقرؤه ملف الإعدادات.

أضف مجموعة توثيق ثانية

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

config/larecipe.php

'sets' => [
    'docs' => [
        // ...
    ],

    'handbook' => [
        'route' => ['prefix' => 'handbook', 'middleware' => ['web', 'auth']],
        'source' => ['driver' => 'repository', 'path' => base_path('handbook')],
        'access' => ['mode' => 'gate'],
        'mcp' => ['web' => ['enabled' => false]],
    ],
],

يسمّي المفتاح default المجموعة التي تستخدمها أوامر artisan وخادم MCP المحلي حين لا تمرّر --set (وهي docs ما لم يحدّد LARECIPE_DEFAULT_SET غيرها). وتشرح صفحة كتل الصلاحيات والتوثيق الخاص أوضاع الوصول والبوابات.

كل ما عدا ذلك

لكل قسم آخر في الملف صفحته:

المفتاح	ما يتحكّم فيه	اقرأ
`review`	هل يسأل وكيلك قبل أن يضيف تغييرات التوثيق إلى git	أوضاع المراجعة
`search`	مشغّل البحث وميزانية الفهرس	البحث
`mcp`	نقطة نهاية MCP للوكلاء والخادم المحلي	خادم MCP
`agents`	`llms.txt` و `llms-full.txt` و `skill.md` وخريطة الموقع	واجهات الوكلاء
`ai`	Ask AI و `larecipe:sync`، بمفتاح المزوّد الخاص بك	اسأل الذكاء الاصطناعي (Ask AI)
`cache`	مخزن الذاكرة المؤقتة للصفحات المُصيَّرة	النشر
`hooks` و `instructions`	فحص pre-push وكتلة `AGENTS.md`	خطّاف pre-push
`ui`	المدة التي تحمل فيها الصفحة المتغيّرة نقطتها في الشريط الجانبي	التنقل

ويسرد مرجع الإعدادات كل مفتاح، وقيمته الافتراضية، ومتغير البيئة الخاص به.

تفاصيل

ضع التوثيق في جذر النطاق

البادئة '' تجعل المجموعة تملك جذر النطاق. وهكذا يعمل هذا الموقع: يفتح larecipe.saleem.dev على صفحة المقدمة، من دون صفحة رئيسية منفصلة. وهذا مدخله، من ملف config/larecipe.php في هذا التطبيق نفسه:

config/larecipe.php

'sets' => [
    'docs' => [
        'route' => [
            'prefix' => '',   // larecipe.saleem.dev opens on the docs: the set owns the domain root
            'domain' => null,
            'middleware' => ['web'],
        ],
        'source' => [
            'driver' => 'repository',
            'path' => base_path('docs'),
        ],
        'access' => [
            'mode' => 'public',
        ],
    ],
],

يُصيّر / الصفحة الرئيسية للإصدار الافتراضي مباشرة. ويُعاد توجيه الروابط الأخرى التي لا تحمل إصدارًا إلى الإصدار الافتراضي.
مساراتك أنت لها الأولوية. يسجّل LaRecipe مساراته بعد مسارات تطبيقك، ويسجّل المجموعة المركّبة على الجذر بعد كل المجموعات الأخرى، فيظل /newsletter في هذا الموقع يصل إلى مسار التطبيق نفسه. ولا يمكن الوصول إلى صفحة توثيق يطابق مسارها أحد مساراتك، فأبقِ المسارات منفصلة.
احذف مسار الترحيب الافتراضي / في Laravel من routes/web.php، وإلا فسيجيب هو بدلًا من توثيقك.
لا يمسّ المسار الشامل /larecipe-assets/ ولا /.well-known/.

المسارات والنطاقات والـ middleware

يثبّت route.domain المجموعة على نطاق واحد: المجموعة التي فيها 'domain' => 'docs.example.com' لا تجيب إلا على ذلك المضيف، وكذلك نقطة نهاية MCP الخاصة بها. أما route.middleware فهو مجموعة الـ middleware التي تحيط بكل مسار توثيق (['web']).

كل روابط التوثيق تتفرّع من البادئة: الصفحات، ونسخ Markdown المقابلة لها بامتداد .md، و llms.txt، و skill.md، و sitemap.xml، والملفات المرفقة، ونقطة نهاية MCP. وكلها تمرّ عبر مجموعة الـ middleware ما عدا نقطة نهاية MCP، كي يستطيع عملاء MCP الإرسال من دون جلسة ولا رمز CSRF.

المصدران

repository (الافتراضي والموصى به): ملفات Markdown في مستودعك، في source.path (base_path('docs')). تنتقل التغييرات في الـ pull requests ملفاتٍ عادية. راجع مصدر المستودع.
database: الصفحات في قاعدة بياناتك، خلف ذاكرة مؤقتة دائمًا. ويقبل أيضًا source.connection، و source.cache (مخزن دائم)، و source.disk (للملفات المرفقة). والتغييرات التي تجري في pull request تُشحن ترحيلاتِ توثيق. راجع مصدر قاعدة البيانات.

للمجموعة مشغّل واحد لكل إصداراتها ولغاتها، ويمكنك أن تنتقل إلى الآخر لاحقًا.

غيّر قيمة افتراضية لمجموعة واحدة

معظم المفاتيح خارج sets قيم افتراضية لكل المجموعات. وتتجاوز المجموعة أحدها بتكراره في مدخلها الخاص. تُدمج قيمها فوق القيم العلوية مفتاحًا بعد مفتاح، فلا تكتب إلا ما يختلف:

config/larecipe.php

'sets' => [
    'handbook' => [
        // route, source, access...
        'review' => 'auto',
        'search' => ['driver' => 'server'],
        'ai' => ['ask' => ['enabled' => true]],
        'agents' => ['llms_full' => false],
    ],
],

ويبيّن مرجع الإعدادات، مفتاحًا مفتاحًا، أيّها يجوز للمجموعة أن تتجاوزه.

بنية المشروع: ما الذي يعيش في مجلد التوثيق.
مرجع الإعدادات: كل مفتاح، مع نوعه وقيمته الافتراضية.
كتل الصلاحيات والتوثيق الخاص: أوضاع الوصول والبوابات بالتفصيل.

أساسيات الإعداد

الإعدادات والمحتوى منفصلان

أضف مجموعة توثيق ثانية

كل ما عدا ذلك

تفاصيل

التالي