# Навигация

← [К разделу «Как собирается сайт»](README.md)

Навигация — независимое дерево ссылок на документы и произвольные URL. Она не
определяет адрес документа и не удаляет документ вместе с пунктом.

## Создание меню

1. Задайте название и короткий уникальный alias, например `main`.
2. Настройте внешнюю обёртку и шаблоны используемых уровней.
3. Выберите группы, которым доступна навигация.
4. Создайте пункты и расположите их перетаскиванием.
5. Вставьте тег `[tag:navigation:main]` в шаблон или блок.

По умолчанию достаточно первого уровня. Второй и третий уровни настраиваются
только если дерево действительно их использует.

## Пункты

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

Дополнительно доступны описание, target, изображение, CSS ID, класс и style.
Изображение выбирается через медиапикер. Для обычной ссылки используйте `_self`,
для осознанного открытия новой вкладки — `_blank`.

Уровень определяется положением пункта в дереве. Перетаскивание меняет родителя,
уровень и порядок; отдельное числовое поле позиции для этого не требуется.

## Шаблоны уровней

Рендер выполняется в следующем порядке:

```text
Обёртка: начало
  Уровень 1: начало
    обычный или активный пункт
    следующий пункт
  Уровень 1: конец
Обёртка: конец
```

`[tag:content]` в начале уровня заменяется готовыми пунктами. Без этого тега
пункты добавляются после начальной разметки. Конец уровня выводится всегда после
его пунктов.

Минимальный первый уровень:

```html
<!-- Обёртка: начало -->
<nav class="site-navigation" aria-label="Основная навигация">

<!-- Уровень 1: начало -->
<ul class="site-navigation-list">[tag:content]

<!-- Обычный пункт -->
<li><a href="[tag:link]">[tag:linkname]</a></li>

<!-- Активный пункт -->
<li class="is-active"><a href="[tag:link]" aria-current="page">[tag:linkname]</a></li>

<!-- Уровень 1: конец -->
</ul>

<!-- Обёртка: конец -->
</nav>
```

## Вложенные уровни

Шаблон родительского пункта должен содержать тег следующего уровня:

```html
<li>
  <a href="[tag:link]">[tag:linkname]</a>
  [tag:level:2]
</li>
```

Для второго уровня аналогично используется `[tag:level:3]`. Если тега нет,
дочерние пункты существуют в дереве, но не попадут в HTML.

Условия `[tag:if_sub_level]`, `[tag:if_no_sub_level]`, `[tag:if_first]`,
`[tag:if_last]`, `[tag:if_every:N]` и парный `[tag:/if]` позволяют менять
разметку без PHP.

## Активная ветка

Система ищет пункт текущего документа или совпадающий alias, строит путь до
корня и применяет активный шаблон к соответствующим пунктам. Для корректного
`aria-current` назначайте его только ссылке текущего пункта, если дизайн
различает текущую страницу и активного родителя.

## Кеш и диагностика

Изменение шаблонов или структуры очищает кеш этой навигации. Ручная очистка
нужна после внешней правки БД.

Если пункт не виден, проверьте:

1. активность пункта и всех родителей;
2. доступ текущей группы к навигации;
3. наличие шаблона нужного уровня;
4. `[tag:level:2]` или `[tag:level:3]` у родителя;
5. внешнюю и уровневую закрывающую разметку.