Laradocs - це Laravel-пакет, який дозволяє розгорнути повноцінний документаційний сайт безпосередньо з Markdown-файлів, що зберігаються всередині вашої кодової бази. Ви пишете документацію поруч із кодом, який вона описує, комітите їх разом у систему контролю версій, а Laradocs автоматично рендерить її за маршрутом /docs з готовою навігацією, SEO-оптимізованими метаданими та адаптивним користувацьким інтерфейсом.
Ключові можливості
Пакет пропонує широкий набір функцій для створення професійної документації:
- Багаторівнева структура файлів - вкладені папки автоматично перетворюються на вкладену навігацію
- Маршрутизація через імена файлів або метадані - поле
slug у front-matter дозволяє перевизначити шляхи
- Перетворення Markdown → HTML на базі CommonMark з підтримкою GitHub Flavored Markdown, таблиць, виносок та інших розширень
- Розширені метадані для кожного файлу - title, description, order, hidden, group, badge, redirect, tags та інші
- Відшліфований стандартний UI - адаптивний дизайн, темний режим, бічна панель, хлібні крихти, автоматичний зміст сторінки, навігація вперед/назад; усе можна публікувати та перевизначати
- Розумне кешування - відрендерений HTML кешується і автоматично інвалідується при зміні файлів
Та багато іншого.
Структура папок стає навігацією
Laradocs автоматично будує бічну панель навігації на основі вашої директорії. Вкладені папки перетворюються на розділи, а файл _index.md виступає як посадкова сторінка розділу. Маршрутизація за замовчуванням слідує за іменами файлів, але ви можете перевизначити шлях за допомогою поля slug у front-matter, коли потрібна URL-адреса, що відрізняється від фактичного розташування файлу.
Створити нову сторінку можна за допомогою генераторної команди:
php artisan make:doc guide/getting-started --title="Getting Started" --order=1
Метадані у Front-Matter
Кожна сторінка містить метадані у форматі YAML front-matter, які керують тим, як вона відображається в навігації та пошуку:
---
title: Getting Started
description: Install and configure the app.
order: 1
group: Basics
---
Підтримувані поля включають title, description, order, hidden, group, badge, redirect, tags та slug. Markdown обробляється через CommonMark з підтримкою GitHub-flavored markdown, таблиць та виносок, а також блоків-виносок (callouts) з використанням знайомого синтаксису GitHub:
> [!TIP]
> Folders become sidebar sections; `_index.md` is a section's landing page.
Змінні та макроси для повторного використання
Щоб уникнути повторення значень на різних сторінках, Laradocs дозволяє реєструвати спільні змінні та багаторазові блоки-макроси з сервіс-провайдера. Змінні інтерполюються в Markdown через синтаксис {{ value }}, а макроси рендеряться через блок @docs():
use PeteBishwhip\Laradocs\Facades\Laradocs;
Laradocs::variables(fn () => ['version' => '1.0.0']);
Laradocs::share('app_name', config('app.name'));
Laradocs::macro('tweet', fn (array $args) => "<a href=\"...\">@{$args['user']}</a>");
Цей підхід забезпечує централізоване керування повторюваним контентом та динамічними значеннями в документації.
SEO, кешування та генерація виводу
Відрендерені сторінки автоматично отримують мета-теги, дані Open Graph та Twitter Cards, а також JSON-LD розмітку. Laradocs також генерує sitemap за адресою {prefix}/sitemap.xml. Пакет кешує відрендерені сторінки і автоматично інвалідує кеш при зміні вихідних файлів.
Ви також можете попередньо відрендерити всі сторінки заздалегідь або очистити кеш вручну:
php artisan laradocs:cache
php artisan laradocs:clear
Системні вимоги та ресурси
Пакет вимагає PHP 8.2 або новішої версії та підтримує Laravel 11, 12 та 13. Детальнішу інформацію можна знайти на офіційному сайті Laradocs, а вихідний код доступний на GitHub.
