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

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

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

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

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

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

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

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

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

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

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

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

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

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

```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-поиска.