larecipe.json

كل مفتاح في larecipe.json، ملف التعريف لمجموعة التوثيق في جذر محتواها. يحمل العرض والبنية، أما البنية التحتية فمكانها config/larecipe.php، والأسرار لا مكان لها هنا أبدًا. ومن دون الملف، تُسمّى المجموعة باسم مفتاحها، بإصدار واحد ولغة واحدة.

{
  "$schema": "https://larecipe.saleem.dev/schemas/3.x/larecipe.json",
  "name": "LaRecipe",
  "description": "Living documentation for Laravel apps. Your coding agents write the docs and keep them current; every reader, human or agent, gets the current answer.",
  "favicon": "/favicon.svg",
  "provenance": false,
  "repository": {
    "url": "https://github.com/saleem-hadad/larecipe",
    "docsUrl": "https://github.com/larecipe/larecipe-docs",
    "docsPath": "docs"
  },
  "versions": [
    {
      "id": "3.x",
      "default": true
    },
    {
      "id": "2.x",
      "status": "maintained"
    }
  ],
  "locales": [
    {
      "code": "en",
      "label": "English",
      "default": true
    },
    {
      "code": "ar",
      "label": "العربية",
      "dir": "rtl"
    }
  ],
  "inserts": {
    "article.after": [
      "Subscribe"
    ],
    "footer": [
      "Byline"
    ]
  },
  "agents": {
    "llmsTxt": {
      "description": "LaRecipe is the docs engine that lives inside your Laravel app: Markdown docs in your repo (or your database), served to people as a fast site and to agents as Markdown, llms.txt, skill.md and MCP, and kept current by your own coding agent in the same pull request as the code.",
      "instructions": "Read the 3.x pages unless the user is on LaRecipe 2. Commands are php artisan larecipe:*; configuration lives in config/larecipe.php, presentation in docs/larecipe.json. Prefer the Reference pages for exact option names."
    }
  }
}

المفاتيح

repository

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

theme

versions

كل عنصر إما معرّف إصدار بصيغة نص، وإما كائن:

راجع الإصدارات.

locales

كل عنصر إما رمز لغة بصيغة نص، وإما كائن:

راجع اللغات.

navbar

يعرض الشريط العلوي repository.url أيقونةً أصلًا، لذا يُستبعد أي رابط في شريط التنقل العلوي يشير إلى الرابط نفسه.

يجب أن تكون روابط شريط التنقل العلوي والتذييل والمستودع روابط http أو https أو mailto، أو مسارات في موقعك. وأي رابط آخر يُستبعد من كل صفحة، ويبلّغ عنه larecipe:validate بالرمز links.unsafe.

redirects

لا تعمل إعادة التوجيه إلا حين لا توجد صفحة في from. وفي مجموعة ذات إصدارات، يسري from الذي لا يذكر إصدارًا على كل الإصدارات: /docs/setup يطابق /docs/3.x/setup و /docs/2.x/setup، و to داخل المجموعة الذي لا يذكر إصدارًا يُبقي القارئ في إصداره. أما from الذي يذكر إصدارًا فيطابق ذلك الإصدار وحده. ويبلّغ larecipe:validate عن إعادات التوجيه التي تدور في حلقة (redirects.loop) والتي تحجبها صفحة (redirects.shadowed).

inserts

المفاتيح نقاط إدراج: header.actions و sidebar.before و sidebar.after و article.before و article.after و toc.after و footer. والقيم قوائم بأسماء مكوّنات بصيغة PascalCase. وتستثني الصفحة نفسها بالمفتاح inserts في ترويستها. راجع نقاط الإدراج.

integrations.analytics

يوضع سكربت كل أداة في كل صفحة متى طابقت قيمُها الشكل الذي يستخدمه مزوّدها، والقيمة التي لا تطابق تُستبعد. ولا تقرأ integrations من larecipe.json إلا مجموعة المستودع. أما مجموعة قاعدة البيانات فتتجاهلها (ويحذّر larecipe:validate بالرمز manifest.integrations): استخدم sets.{key}.integrations.analytics في config/larecipe.php، الذي يقبل المفاتيح نفسها لكل مجموعة ويتقدّم لكل أداة على حدة.

راجع التحليلات.

agents

راجع واجهات الوكلاء.

التحقق

يفحص larecipe:validate الملف ضمن القاعدة manifest.schema: JSON غير الصالح والقيم التي تخالف المخطط أخطاء، وغياب larecipe.json تحذير، والمفتاح العلوي الذي لا يبعد عن مفتاح معروف أكثر من تعديلين تحذير مع الإصلاح (Rename "theem" to "theme".). أما المفاتيح العلوية غير المعروفة الأخرى فتُحفظ، ولا تضيع أبدًا حين تمرّ ذهابًا وإيابًا عبر أي مصدر.

المخطط

يأتي المخطط مع الحزمة في resources/schemas/larecipe.schema.json. يكتب LaRecipe رابط $schema هذا حين ينشئ ملف تعريف أو يرقّيه، وهو $id المخطط:

https://larecipe.saleem.dev/schemas/3.x/larecipe.json

وتقدّم كل مجموعة توثيق أيضًا المخططات المطابقة لإصدارك المثبّت على /{prefix}/schemas/{name}.json، لكل من larecipe و navigation و frontmatter و validate، مع Content-Type: application/schema+json و Access-Control-Allow-Origin: * (/schemas/larecipe.json في هذا الموقع):

لا يحتوي المسار المقدَّم على جزء للإصدار، ويطابق دائمًا حزمتك المثبّتة. ورابط $id الذي يحمل الإصدار يعمل أيضًا: يقدّم هذا الموقع /schemas/3.x/{name}.json، فيحصل المحرر الذي يتبع $schema على الملف.

التالي

• الإعدادات: جانب البنية التحتية، في config/larecipe.php.
• ترويسة الصفحة: إعدادات صفحة واحدة.