Laradocs: пакет для створення версійованої документації в Laravel-додатках

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.