Albireo Doc и другие новости

Расскажу об изменениях в проекте Albireo. (Вы также можете подписаться на мой телеграмм-канал, чтобы получать новости оперативно.) За последнее время, в Albireo было два важных изменения. Первое — доработка админ-панели. Я добавил кнопки для вставки кода в текстовый редактор (сделал на Alpine.js), а также ряд мелких правок, чтобы сделать панель более удобной.

Другое крупное изменение — работа кэша. Раньше он работал только по времени модификации файлов, но не учитывал изменения в структуре каталогов. Это могло приводить к тому, что кэш оказывался невалидным, если загрузить старые файлы или добавить/удалить каталоги. Это частая ситуация. Теперь кэш работает чуть по другому. Он создаёт «снимок» (snapshot) всего каталога, включая каждый файл и его дату модификации и получает числовой полином CRC32. Он сохраняется в отдельном файле. При повтором использовании, кэш сравнивает новое значение со старым и если были изменения, кэш считается невалидным.

Это позволяет отслеживать самые разные ситуации и изменения в каталоге данных. Я об этом рассказывал в телеграмм-канале и даже приводил цифры по нагрузочному тестированию.

Сегодня я выложил ещё одно дополнение, которое условно называется Albireo Doc — это готовое решение для тех разработчиков, которым нужен простой и удобный механизм для создания документации к своим проектам.

Строго говоря создание документации с помощью Albireo Framework, была основной идеей изначально. Но я не хотел её делать сходу, поскольку был ряд других важных задач. Но потихонечку я работал в этом направлении и теперь решил, что можно предложить готовый вариант.

Почему это важно?

В Сети полно отличных проектов, авторы которых не потратили на создание документации достаточного времени. И я их понимаю, потому что создание документации очень сложный процесс. Помимо непосредственной информации, требуется решать ещё и сопутствующие задачи. В первую очередь это внешний вид и навигацию.

Albireo Doc — это готовый для использования шаблон вывода (layout), который поддерживает боковое меню.

То есть страница документация — это самая обычная страница Albireo, только у неё указывается шаблон вывода и свой пункт меню.

...
layout: doc.php

menu[title]: Страницы документации
menu[group]: Основы
menu[order]: 2
...

Albireo сам найдёт параметры menu и на их основе сформирует группы и пункты меню.

Шаблон doc.php разделён на несколько файлов, чтобы можно было кастомизировать дизайн, ссылки, подвал, шапку, css-стили — то есть всё то, что может понадобиться индивидуально. Сам шаблон использует Berry CSS, но это единственная зависимость (нет даже внешнего js-кода).

В качестве дополнения используется сниппет для навигации next/prev — он может выводиться в любой части страницы.

Если проект предполагается выкладывать на GitHub, где не работает PHP, то можно сгенерировать статичные html-файлы. Это стандартная возможность Albireo.

Стоит ещё отметить, что меню можно сформировать и вручную (без параметра menu). Для этого предусмотрен второй вариант вывода — menu-manual.php, который работает с config/menu-data.php, где и хранятся все пункты и группы. Такой вариант удобен тем, что позволяет задавать пункты меню совершенно произвольно: ссылки могут вести на любую страницу сайта или за его пределы.

На сайте Albireo приведена вся информация (там тоже был редизайн) и ссылки на примеры. Думаю, что новые возможности фреймворка окажутся полезными и востребованными. :-)