Встроенная справка

Модуль help показывает Markdown-документацию из корневого каталога help/ в панели управления AVE.cms. Исходные материалы остаются обычными файлами: их можно редактировать в репозитории, просматривать без базы данных и поставлять отдельно от кода модуля.

Установка и доступ

Модуль находится в modules/help и управляется через раздел «Модули». После установки он добавляет отдельный пункт «Справка» и право view_help. Деинсталляция убирает право и интерфейс, но не удаляет каталог help/.

Пользователь видит раздел только при наличии права view_help. Редактирования файлов из панели нет: справочник намеренно работает в режиме только для чтения.

Структура материалов

Каждый Markdown-файл становится отдельным материалом. README.md задаёт страницу каталога, остальные файлы становятся дочерними пунктами:

help/
├── README.md               # обзор справки
└── example/
    ├── README.md           # страница раздела
    ├── installation.md
    └── settings.md

Заголовок берётся из первого # H1. Если его нет, используется имя файла. Папки и материалы сортируются естественным образом, а раздел текущего документа автоматически раскрывается в левом дереве.

Справка установленных модулей

Каталог help/ содержит полный комплект документации, в том числе руководства по необязательным модулям. Это нужно для разработки и автономной поставки справочника, но не перегружает панель: оглавление и поиск показывают страницу конкретного модуля только тогда, когда модуль установлен.

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

Ссылки между материалами

Относительные Markdown-ссылки пишутся как обычно:

[Настройки](settings.md)
[Назад к разделу](README.md)
[Другой раздел](../core/auth.md)

При выводе модуль преобразует их в адреса текущего каталога панели управления. Поэтому переименование adminx/ не требует менять документацию. Внешние HTTP-ссылки открываются в новой вкладке.

Поддерживаемая разметка

Рендерер поддерживает заголовки, абзацы, ссылки, изображения, выделение, строчный код, fenced code blocks, списки, цитаты, разделители и таблицы. Для блоков кода показывается язык и кнопка копирования.

Сырой HTML экранируется и не исполняется. Это защищает панель от случайной вставки скрипта в документацию. Для сложной интерактивной страницы следует создать обычный модульный Twig-шаблон, а не помещать HTML в Markdown.

Поиск и кеш

Поиск учитывает заголовок, подзаголовки и полный текст. Совпасть должны все слова запроса; совпадения в заголовках получают больший вес. Живые результаты появляются только после ввода двух символов.

Индекс хранится в штатном файловом кеше AVE.cms. На запросе модуль сравнивает пути, время изменения и размер .md-файлов. После изменения документа индекс перестраивается автоматически, вручную очищать кеш не требуется.

Ограничения безопасности

индексируются только обычные .md-файлы внутри help/;
симлинки и скрытые пути пропускаются;
пользователь выбирает документ только из готового индекса;
../ и произвольный путь за пределами help/ возвращают 404;
право проверяется и для страницы, и для JSON-поиска.

5.8 KiB Raw Permalink Blame History