Документация Docs/ru/contributing/decisions/0004-manifest-backed-site-navigation-search.md

ADR-0004: навигация и поиск сайта на основе манифеста

Статус: принято
Дата: 2026-07-15
Изменено: 2026-08-01 для локализованной навигации, ограниченного поиска по каждой локали и браузерной проверки собранного сайта
Владельцы: документация, инструменты

Контекст

Документация FOnline публикуется из Markdown репозитория через GitHub Pages/Jekyll по адресу https://fonline.ru. На момент принятия решения маршрут публикации и доставка для ИИ уже принадлежали исходникам, но отрендеренный сайт всё ещё показывал базовую страницу репозитория Slate: у читателей не было постоянной карты документации, встроенного поиска, обозначения текущей версии, мобильной навигации по документации или локального оглавления страницы.

Ручные меню Jekyll дублировали бы Docs/documentation-manifest.json. Hosted search или отдельное приложение сайта добавили бы ещё одну границу развёртывания и доступности. Перемещение всех страниц или добавление front matter только ради темы также смешало бы metadata представления с каноническим техническим корпусом до начала проверенной миграции локалей.

Решение

Docs/documentation-manifest.json владеет группами навигации сайта и политикой поиска в site_delivery. Записи навигации ссылаются на стабильные идентификаторы документов, а не на скопированные заголовки или вручную записанные URL.
BuildTools/docs_site.py детерминированно генерирует:
- _data/docs-site.json, который Jekyll/Liquid использует для навигации, идентичности сайта и репозитория и индикатора rolling source ref;
- assets/docs-search.json для английского и assets/docs-search.ru.json для русского, которые локальный браузерный скрипт использует для статического поиска в пределах локали.
Основная навигация содержит каждый публичный актуальный top-level документ для людей ровно один раз. Detail pages сгенерированных справочников остаются за их index pages, чтобы боковая панель сохраняла удобство просмотра.
Индекс каждой локали включает каждый публичный актуальный документ для людей, доступный в этой локали, в том числе detail pages сгенерированных справочников. Внутренние записи, placeholders, maintainer routes только для ИИ и отсутствующие переводы исключаются. Русская навигация использует английский маршрут как fallback только при отсутствии актуального русского зеркала; результаты поиска никогда не смешивают локали.
Каждый поисковый артефакт хранит компактные взвешенные postings токенов и metadata результата, а не полные тела документов. Заголовки страниц и разделов имеют больший вес, чем текст; технические идентификаторы и их camel-case компоненты остаются доступными для поиска. Чисто числовые токены и термины, встречающиеся более чем в 60% документов локали, исключаются, поскольку не различают результаты. Манифест задаёт жёсткий лимит 1,75 MiB (1 835 008 байт) для каждого locale index, и генерация завершается ошибкой вместо молчаливого исключения документов. Раздельные лимиты не заставляют полное русское зеркало конкурировать с английским за общий бюджет payload. Бюджет повышен с 1,25 MiB, когда проверенное русское зеркало достигло 163 из 195 документов и полный текущий corpus перестал помещаться; ради прохождения проверки ни один документ или класс токенов не был молча удалён.
_layouts/default.html, assets/css/docs.css и assets/js/docs.js образуют тонкий слой рендеринга поверх {{ content }}. Они могут предоставлять адаптивную навигацию, поиск, оглавление страницы, элементы копирования, ссылки на исходники и сохраняемую светлую или тёмную тему, но не владеют техническим текстом.
Интерфейс использует только статические ресурсы репозитория и browser APIs. В нём нет hosted search, удалённой зависимости JavaScript/CSS, сборки приложения, server API или зафиксированного в исходниках сгенерированного HTML.
Видимый индикатор версии показывает master, явно обозначенную как rolling branch, а не стабильный выпуск движка. Версионированная документация остаётся заблокированной до решения по поддержке выпусков и тегов.
Опубликованный знак FOnline является побайтной копией принадлежащего движку Resources/Radiation.png. Он служит только представлению и позднее может быть заменён через проверенное изменение брендинга без влияния на идентичность документов.
Markdown должен оставаться читаемым в репозитории GitHub без Jekyll. Генерация навигации и поиска, контракты layout/static, самостоятельная проверка и сборка GitHub Pages являются обязательными gates в том же изменении, что и правки манифеста или рендеринга.
BuildTools/docs_site_artifact.py проверяет готовое дерево _site, а не выводит корректность рендеринга из исходников. До сохранения артефакта проверяются каждый актуальный и доступный маршрут локали, скопированный static endpoint, canonical URL, язык, accessibility landmark и name, поисковый результат и публикуемая локальная ссылка.
Layout разрешает пары локалей по стабильному идентификатору документа, задаёт язык отрендеренного HTML, подписывает навигацию в активной локали и показывает переключатель EN/RU только при наличии обоих актуальных маршрутов. Browser gate проверяет русский поиск и оба направления перехода между парными страницами.

Последствия

Положительные

Читатели получают стабильную адаптивную оболочку документации, не теряя чистый Markdown и читаемость в GitHub.
Навигация не может молча пропустить новый top-level публичный документ или указать на переименованный путь.
Поиск охватывает сгенерированный технический справочник, не отправляя весь корпус Markdown в браузер, и читатель загружает индекс только активной локали.
Одни стабильные IDs и source ref управляют навигацией для людей, статическим поиском и доставкой для ИИ.
Сайт сохраняет возможность развёртывания существующим действием GitHub Pages и пользовательским доменом.

Издержки

Добавление, перевод или переклассификация публичной документации могут требовать назначения стабильного идентификатора группе навигации и повторной генерации обоих locale indexes, маршрутов, навигации, статуса локализации и AI artifacts.
Клиентский поиск ищет документы текущей ревизии, а не предоставляет версионированный symbol service или semantic retrieval system.
Изменения layout требуют и тестов взаимодействия на уровне исходников, и проверки артефакта Jekyll, поскольку локальные статические тесты не доказывают рендеринг Liquid.
Немигрированные плоские английские пути остаются видимыми во время миграции дерева локалей. Проверенные группы миграции доказывают канонические страницы EN/RU, переключение по stable ID, русский поиск и долговечные legacy pointer routes; ADR-0006, статус локализации и генерируемый каталог маршрутов владеют текущим покрытием и остатком.

Отклонённые варианты

Front matter каждой страницы, принадлежащий теме: отклонён, поскольку дублирует заголовки и порядок и связывает технический Markdown с одной темой.
Hosted search: отклонён, поскольку добавляет credentials, задержку индексации, privacy и доступность сервиса к статической документации.
Ручной список документов JavaScript: отклонён, поскольку разошёлся бы с манифестом и AI catalog.
Полные тела Markdown в search JSON: отклонены, поскольку дублируют корпус в браузерном payload и плохо масштабируются вместе со сгенерированным справочником.
Приложение документации на Node: отклонено ADR-0001; издателем остаётся GitHub Pages/Jekyll.

Проверка

python BuildTools/tests/test_docs_site.py
python BuildTools/tests/test_docs_site_layout.py
python BuildTools/tests/test_docs_site_artifact.py
python BuildTools/tests/test_docs_browser.py
python BuildTools/docs_site.py --check
python BuildTools/docs_site_artifact.py --site-dir _site
npm --prefix BuildTools/docs-browser run audit
python BuildTools/tests/test_docs_validate.py
python BuildTools/docs_validate.py
проверка артефакта GitHub Actions Build documentation site на desktop и mobile widths