Albireo CMS 2025.06.03

Создание документации с помощью Albireo CMS

Albireo CMS прекрасно подходит для создания документации для любых проектов. В комплекте системы есть все готовые решения.

Для Albireo CMS нет принципиальной разницы между обычной страницей сайта и страницей документации. Вопрос больше лежит в области того, как именно вы хотите организовать документацию для своего проекта.

Все рабочие примеры есть в комплекте Albireo CMS.

Есть два варианта. Первый — это весь сайт будет являться документацией, а значит все настройки будут иметь отношение ко всем страницам вашего сайта.

Второй вариант — когда документация является только частью вашего сайта.

Пример для первого варианта — сайт Berry CSS — в нём все страницы выполнены в едином стиле, где нет шапки, подвала как у обычного сайта. Только навигация и блок контента.

Второй пример — документация MaxSite CMS, которая представляет собой лишь часть общего сайта. Поэтому в документации выводится шапка, подвал и прочие блоки обычного сайта.

Стоит особо отметить, что на самом деле Albireo CMS никак вас не ограничивает: вы можете использовать любые варианты построения документации, а также добавлять шапки, подвалы и любые другие блоки. Или можете использовать сразу два варианта документации для своего сайта. Вопрос только в удобстве и не более того.

Выбор layout-файла

Для вывода документации предусмотрено два layout-файла: doc1.php (первый вариант) и doc2.php (второй вариант).

Общий подход

Рассмотрим пример страницы документации в качестве отправной точки.

<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
/**

# title страницы и description
title: Demo doc1
description: [title]

# подключить layout-шаблон
layout: doc1.php

# файл конфигурации doc-шаблона
doc.config: doc1.php

# тип файла указан в конфигурационном файле
type: doc

# название пункта меню
doc.menu.title: Demo-page1

# раздел меню и его порядок
doc.menu.path: 01_General

# класс иконки (если нужно)
doc.menu.icon: bi-check

# добавочный текст справа для неактивного пункта (если нужно)
doc.menu.add: <span class="b-inline b-right bi-bookmark"></span>

# добавочный текст справа для активного пункта (если нужно)
doc.menu.add.active: <span class="b-inline b-right bi-bookmark-fill"></span>

# навигация вверху (если нужно)
extras.start[doc-nav.php]: +

# навигация внизу (если нужно)
extras.end[doc-nav.php]: +

# ссылка на редактирование страницы (если нужно)
extras.start[edit-link.php]: +

# отключим остальные блоки сайта
headers: -
footers: -
comments: -
other-pages: -
css.layout: -
sitemap: -
nav: -
nav-top: -

**/
?>

h1 Demo page

Content
...

Основные поля следующие:

  • layout: doc1.php — этим мы подключаем шаблон вывода.
  • doc.config: doc1.php — настройка документации хранится в отдельном файле.
  • type: doc — файлы документации должны иметь свой тип, чтобы отличаться от других страниц сайта.
  • doc.menu.title: Demo page — указывается название пункта в меню навигации.
  • doc.menu.path: 01_General — иерархия меню.

Поскольку на странице не нужны будут прочие блоки, то они принудительно отключаются.

Точно также строится страница и для doc2.php, с той разницей что здесь уже не нужно отключать шапку и подвал сайта (headers, foorers).

Прочие подключения

Все остальные подключения выполняются привычным способом. Например часто требуется подключить подсветку синтаксиса:

use.highlight: +

Если используется лайтбокс:

use.glightbox: +

Все эти подключения указываются на странице как обычно.

Использование page-data-файла

Для того, чтобы упростить сопровождение документации, есть смысл вынести основные данные полей в отдельный файл. Он размещается в каталоге конфигурации, например так: website/config/page-data/doc-data.php.

В этот файл можно перенести все те поля, которые будут повторяться на каждой странице.

<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');

return [
    'description' => '[title]',
    'layout' => 'doc1.php',
    'doc.config' => 'doc1.php',
    'type' => 'doc',
    'extras.start[doc-nav.php]' => 1,
    'extras.start[edit-link.php]' => 1,
    'extras.end[doc-nav.php]' => 1,
    'headers' => 0,
    'footers' => 0,
    'other-pages' => 0,
    'css.layout' => 0,
    'sitemap' => 0,
    'stat.page' => 0,
    'stat' => 0,
    'comments' => 0,
    'nav' => 0,
    'nav-top' => 0,
];

# end of file

После этого страница документации сокращается:

<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
/**

title: Demo doc1
file-page-data: doc-data.php

doc.menu.title: Demo-page1
doc.menu.path: 01_General

# doc.menu.icon: bi-check
# doc.menu.add: <span class="b-inline b-right bi-bookmark"></span>
# doc.menu.add.active: <span class="b-inline b-right bi-bookmark-fill"></span>

**/
?>

h1 Demo page

Content
...

Если стоит задача поменять какое-то поле из page-data-файла, то оно просто указывается как обычно. Например, если нужно отключить вывод ссылки на редактирование:

extras.start[doc-nav.php]: -

Боковая панель навигации

Боковая панель строится как блоки секций, которые задаются в виде полей doc.menu.path и doc.menu.title.

Поле doc.menu.title задаёт название ссылки в меню. Это название никак не связано с title, поэтому можете подбирать его так, чтобы оно красиво выводилось.

Поле doc.menu.path определяет секцию меню. Но строится как НОМЕР_НАЗВАНИЕ.ПОРЯДОК, например

doc.menu.path: 01_General.01

Указывает, что это первая секция (01), название «General» и порядок «01». Еще несколько примеров:

doc.menu.path: 02_Советы и подсказки.07
doc.menu.path: 02_Советы и подсказки.07.1
doc.menu.path: 03_Шаблоны
doc.menu.path: 7_Основы.2

Таким образом, страница должна относиться к какой-то секции, а числа в конце указывают на порядок страницы внутри секции. Номер секции нужен для того, чтобы обеспечить точный порядок. Если секций меньше 10, то число можно указывать от 0 до 9. Если сопроводить число нулём, то секций может быть 100 (0..99).

С помощью поля doc.menu.icon можно задать маркер пункта меню — это css-класс, например из Bootstrap Icons. Если вы хотите поменять маркер у всех пунктов, то укажите doc.menu.icon в page-data-файле.

Поле doc.menu.add используется как html-добавка к пункту меню. Например если нужно выделить страницу особым образом.

Дополнительная навигация по страницам

Вы можете задать дополнительную навигацию с помощью extras-файлов. Одна из них будет выводиться перед контентом, а вторая после:

extras.start[doc-nav.php]: +
extras.end[doc-nav.php]: +

Если на странице какая-то навигация не нужна, то её можно отключить как обычно:

extras.start[doc-nav.php]: -
extras.end[doc-nav.php]: -

Порядок страниц через имена файлов

Albireo CMS поддерживает автоматическую сортировку по именам файлов. Система понимает такой формат файлов страниц ЧИСЛО.имя.php. Число нужно для того, чтобы по имени файла можно было бы сразу понять его порядок. При ведении документации это хорошая возможность. Например такие имена файлов:

01.directories.php
02.pages.php
03.page-structure.php
04.page-fields.php
05.configuration.php
06.users.php
07.admin-panel.php
08.images.php
09.textsimple.php

Система автоматически отбросит числовую часть, а из оставшейся сформирует корректный slug (адрес) страницы.

Если вы будете использовать нумерацию файлов, то можно упростить поле doc.menu.path и указывать только название секции без порядка файла:

doc.menu.path: 01_General

Albireo CMS автоматически отсортирует файлы по порядку их имени.

Ведущий ноль в числе нужен, чтобы обеспечить корректную алфавитную сортировку. Если у вас более 100 файлов, то используйте два ведущих нуля.

Разделы документации

Разделы документации организуются с помощью doc.menu.path, но это только для блока навигации. Что касается ссылок, то удобно размещать документацию по отдельным каталогам.

introduction/
    01.directories.php
    02.pages.php
    03.page-structure.php
    04.page-fields.php
    05.configuration.php
    
build-website/
    01.build-website.php
    03.tini-slider.php
    04.grid-gallery.php
    05.css-gram.php
    06.fonts.php

Если не указывать поле slug, то система автоматически сформирует адреса страниц с учётом их подкаталога.

В случаях, когда адреса не должны содержать подкаталоги, то можно явно указывать поле slug у каждой страницы. Альтернативой может быть именование имен файлов с учетом номера раздела.

101.book.php
102.plugins-widgets.php
103.publication.php
104.site-template.php

301.install.php
302.screenshots.php
303.sites-variant.php

401.scheme-maxsite.php
402.section-options.php
403.php-tmpl.php
404.set-get.php
405.shortcode.php
406.lang.php

501.template-dispatcher.php
502.template-type-file.php
503.template-main.php

В данном примере номер файла начинается с числа, указывающий (условно) на номер раздела. Таким образом файлы хоть и в одном каталоге, но визуально их легко различить по разделам (сам раздел всё также указывается в doc.menu.path каждого файла).

Конфигурация

С помощью конфигурации можно изменить внешний вид layout-файла. По умолчанию файлы конфигурации doc1.php и doc2.php размещаются в системном каталоге system/config. Вам нужно скопировать нужный файл в свой каталог сайта: website/config и работать уже в нём.

Конфигурация содержит настройки всех частей шаблона. По умолчанию вёрстка выполнена на Berry CSS в палитре primary.

Для смены цветов вы можете использовать стандартные возможности Albireo CMS. Например с помощью полей для работы с CSS.

Если смена дизайна требует переделки html-кода, то сделайте копию layout-файла, например doc-my.php и работайте уже с ним.

Вы можете использовать уже готовые цветовые темы из Berry CSS. Например для изменения цветовой темы на red просто укажите в поле страницы (или в page-data-файле):

css.theme: red.css

Все доступные цвета размещаются в каталоге templates/default/assets/css/themes. Сейчас в нём 19 файлов.

Документация как отдельный сайт

Если документация представляет собой самостоятельный сайт, то можно ещё немного упростить её сопровождение. Поскольку поля будут относиться ко всем страницам сайта, то можно отказаться от отдельного page-data-файла и всё что нужно, прописать в website/config/page-data.php и website/config/config.php.

Тогда поле file-page-data: doc-data.php у страниц не требуется.