Меню и разделы

Docara строит левое меню из структуры Markdown-файлов. Отдельного файла со списком пунктов нет: добавьте страницу — она появится в меню, переместите файл — изменится её место в дереве.

Как строится дерево

Иерархия берётся из каталогов и Markdown-файлов, а не из публичного slug. Страница раздела и одноимённый каталог объединяются в один пункт: ссылка открывает обзор раздела, а отдельная кнопка раскрывает вложенные материалы.

content/
  guides.md
  guides/
    install.md
    configuration.md
    configuration/
      theme.md
      advanced/
        overrides.md

Вместо guides.md можно использовать guides/index.md, но не обе формы сразу. Каталог без страницы-обзора остаётся группой без ложной ссылки.

Внутренняя модель не ограничивает количество уровней. Интерфейс и SIMAI Framework проверены на четырёх видимых уровнях; более глубокие уровни сохраняют семантику и используют оформление четвёртого уровня.

Порядок и видимость

Порядок и видимость пункта задаются в соседнем файле <page>.page.json, а для страницы раздела — в файле обзора, например guides.page.json:

{
  "schema": "docara.page.v1",
  "navigation": { "order": 20 }
}

• navigation.order — неотрицательное целое число; меньшее значение стоит выше среди соседей;
• страница без order идёт после страниц с явным order;
• при равенстве используется стабильный путь исходного файла;
• navigation.hidden: true убирает страницу из меню.

Задавайте order явно у всех страниц раздела: иначе порядок будет зависеть от имён файлов, а они на английском и не совпадают с порядком чтения.

Скрытая страница остаётся публичным HTML и доступна по прямой ссылке. Чтобы убрать её и из поиска, дополнительно задайте search.indexed: false. Если у скрытой страницы есть видимые потомки, ветка остаётся в меню как группа без ссылки. Ни hidden, ни indexed не закрывают доступ к странице.

Верхнее меню сайта

Ключевые ссылки в шапке задавайте в корневом content/<locale>/section.json. Подписи принадлежат конкретному языку, поэтому каждая языковая версия может иметь свой состав и порядок:

{
  "schema": "docara.section.v1",
  "header_navigation": {
    "enabled": true,
    "items": [
      {"id": "home", "label": "Главная", "href": "/ru/"},
      {"id": "start", "label": "Быстрый старт", "href": "/ru/start/quick-start/"},
      {"id": "components", "label": "Компоненты", "href": "/ru/components/"},
      {"id": "github", "label": "GitHub", "href": "https://github.com/simai/docara"}
    ]
  }
}

id — стабильный технический идентификатор, label — локализованная подпись, href — внутренний путь, якорь или безопасный HTTPS-адрес. Допустимо не более восьми одноуровневых пунктов. Чтобы отключить меню во вложенном разделе, задайте "header_navigation": {"enabled": false}. Чтобы заменить унаследованный список, передайте новый items: списки наследуются целиком, а не по индексам.

Пункт верхнего меню отмечается не только на своей странице, но и на всех страницах своего раздела. При сборке Docara выбирает один пункт: сначала тот, что стоит выше всех в цепочке разделов текущей страницы в навигации, а если такого нет — пункт с самым длинным совпадающим началом адреса. Пункт главной страницы отмечается только на ней самой. Текущая страница получает aria-current="page", пункт раздела — aria-current="true"; оба выглядят так же, как активный пункт левого меню.

На широком экране верхнее меню располагается между брендом и действиями шапки. На узком оно не сжимается и не обрезается: ссылки переходят в единую панель «Навигация», где сначала идёт раздел «Главное», затем дерево документации. На лендинге без дерева та же панель содержит только ключевые ссылки.

Всё дерево или только раздел

navigation.scope=site показывает в боковой панели всё дерево сайта. navigation.scope=section оставляет только дочерние страницы активного раздела первого уровня. Верхнее меню, хлебные крошки, поиск и переходы между страницами продолжают использовать полное дерево.

Текущая страница и узкий экран

Текущая ссылка получает aria-current="page", а все её предки раскрываются автоматически. На широком экране дерево закреплено слева. На узком оно открывается поверх статьи в окне «Навигация», поэтому содержание не сдвигается. Escape, кнопка закрытия и щелчок по затемнённому фону закрывают панель и возвращают фокус на кнопку, которая её открыла.

Хлебные крошки, содержание страницы и переходы «Предыдущая» и «Следующая» строятся из того же дерева, поэтому порядок не расходится; они описаны в разделе «Контекст чтения». Лендинг (preset: landing) их не выводит.

Меню рисует один Smart-компонент docara.navigation в трёх видах: header (верхнее меню), tree (левое дерево) и compact (мобильная панель). Настройки сайта не выбирают шаблон, класс или способ отрисовки меню; как заменить или дополнить меню в области макета, описано в разделе «Области макета».

После изменения

После добавления, переименования или удаления страницы, изменения order, hidden или пунктов верхнего меню выполните полную сборку: меню, поиск, хлебные крошки и переходы между страницами — общие производные данные всех страниц. При переименовании страницы добавьте перенаправление со старого адреса.

См. также

• Контекст чтения — хлебные крошки и переходы
• Перенаправления
• Поля navigation и header_navigation