Контекст чтения

Контекст чтения помогает понять три вещи: где находится страница, что есть внутри неё и куда перейти дальше. Docara строит его автоматически из структуры Markdown-проекта и заголовков статьи.

Что появляется на странице

Для preset docs доступны четыре настройки:

На широком экране «Содержание» закреплено справа. Ниже 1152 px режим auto показывает компактную кнопку «Содержание», только если в оглавлении не меньше четырёх пунктов или есть вложенный заголовок H3–H6. Короткая плоская страница не тратит первый экран на лишний элемент. На узком экране переходы «Предыдущая» и «Следующая» складываются друг под другом.

Значение always принудительно оставляет мобильную кнопку при непустом оглавлении, а never скрывает её независимо от длины страницы. Эти режимы не влияют на закреплённое содержание десктопной версии.

Если путь содержит больше трёх уровней, Docara оставляет видимыми корень и текущую страницу, а промежуточные уровни сворачивает в кнопку с многоточием. Она раскрывает полную цепочку без перехода на другую страницу. До загрузки JavaScript и при его отключении вся серверная цепочка остаётся доступной и на узком экране прокручивается внутри своей области.

Сворачивание использует базовый компонент breadcrumbs SIMAI Framework. Docara не хранит отдельную копию пути и не создаёт собственный компонент: источник уровней остаётся единым с деревом разделов и переходами страниц.

Preset landing не выводит хлебные крошки, оглавление и переходы: эти элементы относятся к чтению документации, а не к устройству лендинга.

Настройка сайта и раздела

Обычно достаточно включить контекст один раз в docara.json:

{
  "schema": "docara.site.v1",
  "reading": {
    "breadcrumbs": true,
    "toc": true,
    "mobile_toc": "auto",
    "toc_depth": 3,
    "previous_next": true
  }
}

Раздел может изменить только нужное поле и сохранить остальные значения:

{
  "schema": "docara.section.v1",
  "reading": { "toc_depth": 4 }
}

Настройка одной страницы

Чтобы оставить стабильные ссылки на заголовки, но убрать все вспомогательные поверхности, добавьте в <page>.page.json:

{
  "schema": "docara.page.v1",
  "reading": {
    "breadcrumbs": false,
    "toc": false,
    "previous_next": false
  }
}

Docara всё равно назначит заголовкам детерминированные id. При неизменном тексте и порядке заголовков ссылка на раздел статьи продолжит работать, даже если оглавление скрыто. Переименование заголовка меняет автоматически сформированный якорь и требует проверки входящих deep links.

Как формируются якоря

Все заголовки H1–H6 получают детерминированный Unicode-якорь. Регистр приводится к нижнему, пробелы и знаки пунктуации превращаются в дефис:

## Установка и настройка
→ #установка-и-настройка

Если одинаковый заголовок повторяется, Docara добавляет суффикс -1, -2 и далее. Заголовок без букв и цифр получает основу section. В оглавление входят только H2–H6 в пределах toc_depth; H1 остаётся заголовком страницы.

В Markdown можно ссылаться на получившийся раздел обычной локальной ссылкой:

[Перейти к настройке](#установка-и-настройка)

Статическая проверка сборки отклонит ссылку на отсутствующий фрагмент и страницу с повторяющимся HTML id.

Порядок страниц

Хлебные крошки и переходы используют единую каноническую топологию:

1. структура каталогов задаёт вложенность;
2. navigation.order задаёт порядок соседей;
3. при равенстве применяется стабильный путь источника;
4. страницы другого языка и preset landing не становятся соседями документа;
5. скрытая страница остаётся частью пути, но не становится целью перехода.

navigation.hidden: true скрывает страницу только из глобального меню. Если у скрытой страницы есть видимые потомки, ветка остаётся в меню как группа без ложной ссылки. Благодаря общей топологии хлебные крошки скрытой страницы не теряют её реальный путь, а переходы находят ближайших видимых соседей.

Главная страница не показывает хлебные крошки из единственного пункта. Страница только с H1 не показывает пустое оглавление, но сам H1 всё равно получает якорь.

Когда отключать элементы

• Отключите toc, если страница короткая и состоит только из одного заголовка.
• Используйте mobile_toc: "never", если мобильная навигация не нужна даже на длинной странице, или "always", если автору важен постоянный быстрый доступ.
• Уменьшите toc_depth, если глубокие технические подпункты перегружают правую область.
• Отключите previous_next для автономной справочной страницы, где порядок чтения не важен.
• Отключите breadcrumbs только если путь уже однозначно объяснён самой страницей; левое дерево при этом остаётся доступным.

Фактические итоговые значения и их источники можно проверить в resolved page plan.