Создание документации с помощью 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 у страниц не требуется.