Laradocs: مستندات نسخهبندیشده داخل خود اپ لاراول
لاراول
پیاچپیخلاصهٔ کاملتر
به گفتهٔ مقاله، Laradocs یه پکیج لاراوله که یه سایت مستندات کامل رو از فایلهای مارکداون که داخل خود کدبیس نگه میداری میسازه. ایدهٔ اصلیش اینه که داک رو کنار همون کدی که توضیح میده بنویسی، با هم کامیتشون کنی، و Laradocs اونا رو روی مسیر /docs با منو، متادیتای مناسب برای سرچ و یه رابط واکنشگرا رندر کنه.
منوی کناری مستقیم از چیدمان پوشههات ساخته میشه: پوشههای تودرتو تبدیل به بخشهای تودرتو میشن و یه فایل _index.md نقش صفحهٔ فرود اون بخش رو بازی میکنه. بهصورت پیشفرض مسیرها از روی اسم فایلها تعیین میشن، ولی اگه بخوای یه URL متفاوت با محل فایل داشته باشی میتونی با فیلد slug تو فرانتمتر مسیرو بازنویسی کنی.
هر صفحه یه سری متادیتا تو فرانتمتر YAML داره که کنترل میکنه تو منو و سرچ چطوری ظاهر بشه. فیلدهای پشتیبانیشده شامل عنوان، توضیح، ترتیب، مخفیبودن، گروه، نشان (badge)، تغییرمسیر صفحه، برچسبها و مسیر سفارشی هستن. خود مارکداون هم با CommonMark پردازش میشه که از GFM، جدولها و فوتنوتها پشتیبانی میکنه و بلاکهای callout هم با همون سینتکس آشنای گیتهاب کار میکنن.
برای اینکه مجبور نشی یه مقدار رو تو صفحههای مختلف تکرار کنی، Laradocs بهت اجازه میده متغیرهای مشترک و بلاکهای ماکروی قابلاستفادهٔ مجدد رو از تو یه سرویسپروایدر ثبت کنی. متغیرها با سینتکس {{ value }} داخل مارکداون جاگذاری میشن و ماکروها هم با یه بلاک @docs() رندر میشن:
Laradocs::variables(fn () => ['version' => '1.0.0']);
Laradocs::share('app_name', config('app.name'));از نظر سئو و خروجی هم هر صفحه بهصورت خودکار متاتگ، دیتای Open Graph و Twitter card و JSON-LD میگیره و یه sitemap هم زیر {prefix}/sitemap.xml تولید میشه. صفحههای رندرشده کش میشن و کش هم با تغییر فایلهای منبع خودبهخود باطل میشه؛ میتونی با دستور php artisan laradocs:cache همهچیزو از قبل رندر کنی یا با laradocs:clear کش رو پاک کنی.
نویسنده میگه این پکیج به PHP 8.2+ نیاز داره و از لاراول ۱۱، ۱۲ و ۱۳ پشتیبانی میکنه. UI پیشفرضش هم دارکمود، breadcrumb، فهرست داخل صفحه و دکمههای قبلی/بعدی داره که همهشون قابل انتشار و بازنویسیان.
نکات کلیدی:
- مستندات از فایلهای مارکداون داخل کدبیس ساخته میشه و کنار کد کامیت میشه
- ساختار پوشهها بهصورت خودکار به منوی کناری تبدیل میشه و _index.md صفحهٔ فرود بخشه
- متادیتای فرانتمتر مسیر، ترتیب، گروه و نمایش هر صفحه رو کنترل میکنه
- متغیرها و ماکروها جلوی تکرار مقدارها رو تو صفحههای مختلف میگیرن
- متاتگ، Open Graph، JSON-LD و sitemap خودکار تولید میشن و خروجی هم کش میشه
