Deploy и GitHub Pages

Документационный сайт этого репозитория публикуется на GitHub Pages через GitHub Actions и собирается как статический VitePress-сайт.

Что именно деплоится

• контент из docs/;
• конфиг и тема из docs/.vitepress/;
• сгенерированный static output из docs/.vitepress/dist;
• profile-страница организации через profile/README.md.

Как устроен pipeline

1. Push в main или ручной workflow_dispatch.
2. GitHub Actions ставит зависимости.
3. Выполняется npm run docs:build.
4. Артефакт публикуется в GitHub Pages.
5. Для project pages корректный base вычисляется из GITHUB_REPOSITORY.

Что уже настроено

Файл	Роль
.github/workflows/deploy-docs.yml	build и публикация docs
docs/.vitepress/config.ts	навигация, sidebar, search, Pages base
docs/.vitepress/theme/index.ts	подключение кастомной темы
docs/.vitepress/theme/style.css	визуальный слой документации

Технические особенности

Почему сайт статический

• документация не зависит от backend runtime;
• GitHub Pages не требует отдельного сервера;
• контент удобно ревьюить как обычные markdown-диффы;
• инфраструктурный риск для docs минимален.

Почему отключена смена темы

• документация оформлена как единый светлый сайт в визуальном языке NPPWEB;
• технические схемы и таблицы читаются стабильнее без двух разных цветовых режимов;
• это снижает количество случайных визуальных регрессий и упрощает поддержку стилей.

Локальная проверка

npm install
npm run docs:dev

Production preview:

npm run docs:build
npm run docs:preview

Что проверять перед push

• главная страница открывается без layout-ошибок;
• навигация и sidebar ведут на существующие страницы;
• поиск по docs не ломается;
• таблицы и callout-блоки нормально читаются на мобильной ширине;
• нет битых ссылок на репозитории, экраны и маршруты.

Частые проблемы

Симптом	Что проверить
на Pages ломается навигация	base в config.ts, имя репозитория, абсолютные ссылки
локально всё ок, а на Pages пусто	workflow permissions и Settings -> Pages -> GitHub Actions
стили не применяются	импорт theme/style.css в theme/index.ts
favicon или ассеты не открываются	путь в head и public/

Эксплуатационные рекомендации

• держать технические и аналитические разделы в одном сайте, но не смешивать их на одной странице;
• обновлять docs сразу после архитектурных или продуктовых изменений;
• фиксировать ключевые pipeline-решения, если они влияют на качество данных и отчётов;
• использовать docs как точку входа для онбординга, а не только как “справочник после факта”.

Где менять контент

• обзор и старт: docs/index.md, docs/getting-started.md
• архитектура и аналитика: docs/architecture.md, docs/analytics.md
• карты репозиториев: docs/repositories/*
• визуальный слой: docs/.vitepress/theme/*
• pipeline публикации: .github/workflows/deploy-docs.yml