الإصدارات

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

docs/larecipe.json

{
  "versions": [
    { "id": "3.x", "default": true },
    { "id": "2.x", "status": "maintained" }
  ]
}

docs/
- larecipe.json
- 3.x/
  - navigation.json
  - index.md
- 2.x/
  - navigation.json
  - index.md

لكل إصدار روابطه (/docs/3.x/installation)، وتنقله، وفهرس بحثه، وملف llms.txt الخاص به، ويتنقّل القرّاء بينها من الشريط العلوي. والمجموعة التي لا إصدارات لها تعمل أيضًا: تبقى صفحاتها مباشرة في docs/ حتى تضيف أول إصدار.

وهذا الموقع مثال على ذلك: يقدّم 3.x، التوثيق الحالي، و 2.x، توثيق LaRecipe 2 الذي حوّلته ترقية الإصدار 2.

أضف إصدارًا

انسخ التوثيق الحالي إلى إصدار جديد، واجعله الافتراضي:

bash

php artisan larecipe:make:version 4.x --default

ينسخ الأمر مجلد الإصدار الافتراضي ويضيف الإصدار الجديد إلى larecipe.json. مرّر --from=3.x لتنسخ إصدارًا آخر، و --dry-run لترى الملفات التي سيكتبها. ثم عدّل الصفحات التي تغيّرت، وتحقّق من ذلك الإصدار وحده:

bash

php artisan larecipe:validate --docs-version=4.x

وحين لا تكون للمجموعة إصدارات بعد، سمِّ الإصدار الذي تنتمي إليه صفحاتها الحالية بالخيار --current-as. ينقلها الأمر إلى ذلك المجلد قبل أن ينسخ:

bash

php artisan larecipe:make:version 2.x --current-as=1.x --default

يبقى larecipe.json و theme.css ومجلد skills/ في الجذر: فهي تخص المجموعة لا إصدارًا بعينه. ويعمل الأمر على مجموعات المستودع، أما مجموعة قاعدة البيانات فتضيف الإصدارات عبر ملف التعريف الخاص بها، بأداة MCP update_manifest.

مفاتيح الإصدار

المفتاح	القيمة الافتراضية	المعنى
`id`	مطلوب	اسم المجلد ومقطع الرابط، مثل `3.x`.
`label`	قيمة `id`	ما يعرضه مبدّل الإصدارات.
`status`	`current`	`current` أو `maintained` أو `deprecated` أو `archived`. ويصف `llms.txt` كل إصدار بها، فيعرف الوكلاء أيّها يفضّلون.
`default`	`false`	الإصدار الذي يصل إليه القرّاء. وحين لا يقول أي إصدار `true`، يكون الأول هو الافتراضي.
`visibility`	`public`	الإصدارات `private` تحتاج إلى البوابة (gate) `viewLarecipe` في كل واجهة. راجع كتل الصلاحيات والتوثيق الخاص.

ويمكن أن يكون الإصدار نصًا مجرّدًا ("versions": ["3.x", "2.x"]) حين لا يحتاج إلى أكثر من معرّف.

تفاصيل

الروابط، والروابط القديمة، والمبدّل

تعيش الصفحة ذات الإصدار على /{prefix}/{version}/{path}. وفي هذا الموقع، المجموعة مركّبة على جذر النطاق، فصفحة التثبيت هي /3.x/get-started/installation، ونسخة Markdown الخاصة بها هي الرابط نفسه مع .md.

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

وإعادة التوجيه التي لا يحمل from فيها إصدارًا تنطبق على كل إصدار، و to الذي لا يحمل إصدارًا يُبقي القارئ في إصداره. اكتب الإصدار، كما في /3.x/setup، لتعيد توجيه إصدار واحد فقط.

الرابط الأساسي (canonical) لكل صفحة هو رابطها هي في إصدارها هي: فصفحة 2.x رابطها الأساسي عنوانها في 2.x.

يسرد المبدّل في الشريط العلوي كل الإصدارات بتسمية label الخاصة بكل منها. واختيار أحدها يُبقيك على الصفحة نفسها حين تكون موجودة في الإصدار الآخر، ويأخذك إلى الصفحة الرئيسية لذلك الإصدار حين لا تكون موجودة.

ما الذي يحصل عليه الوكلاء لكل إصدار

يسرد /llms.txt الإصدارات مع حالاتها، ثم صفحات الإصدار الافتراضي، فيصل الوكيل إلى التوثيق الحالي في طلب واحد.
يسرد /{version}/llms.txt صفحات ذلك الإصدار، ويحوي /{version}/llms-full.txt نصّها الكامل.
تأخذ أدوات MCP search_docs و read_page و list_pages الوسيط version، وتستخدم الإصدار الافتراضي من دونه.

وفي هذا الموقع، تجدها في الفهرس الجذري، وفهرس 3.x، وفهرس 2.x.

كل خيارات larecipe:make:version

يقرأ larecipe:make:version كلا شكلي قائمة versions، ويكتبها بالطريقة التي كتبتها بها. مقروءة مباشرة من هذا التطبيق:

Command larecipe:make:version

Add a docs version by copying an existing one

php artisan larecipe:make:version [--from [FROM]] [--default] [--current-as [CURRENT-AS]] [--set [SET]] [--dry-run] [--] <version>

Arguments
Argument	Description	Default
`version`	The new version id, for example 3.x (required)

Options
Option	Description	Default
`--from=FROM`	Copy the pages of this version (default: the default version)
`--default`	Make the new version the default
`--current-as=CURRENT-AS`	For a set without versions yet, the version its current pages belong to
`--set=SET`	The doc set (default: the default set)
`--dry-run`	Show what would change without writing anything

اللغات: الصفحة نفسها بأكثر من لغة، داخل كل إصدار.
التنقل: ملف navigation.json لكل إصدار.
مرجع larecipe.json: كل مفتاح في ملف التعريف.

الإصدارات

أضف إصدارًا

مفاتيح الإصدار

تفاصيل

التالي