Deploy и GitHub Pages

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

Что публикуется

В Pages уходит:

контент из docs/;
конфиг из docs/.vitepress/;
статический build output;
организационная profile-страница из profile/README.md.

Почему docs вынесены в `.github`

Это удобно по нескольким причинам:

документация живёт рядом с организационными и Pages-настройками;
docs можно публиковать независимо от runtime-сервисов;
markdown-диффы проще ревьюить, чем контент в сторонней wiki;
один репозиторий может быть точкой входа во всю экосистему.

Как устроен pipeline

Push в main или ручной workflow_dispatch.
CI ставит зависимости.
Выполняется npm run docs:build.
Артефакт публикуется в GitHub Pages.
base вычисляется автоматически из GITHUB_REPOSITORY.

Ключевые файлы

Файл	Назначение
`.github/workflows/deploy-docs.yml`	build и publish
`docs/.vitepress/config.ts`	навигация, sidebar, search, base
`docs/index.md`	главная страница
`docs/repositories/*`	карта сервисов
`docs/operations/*`	эксплуатационные документы
`profile/README.md`	GitHub profile-page организации

Локальная работа с docs

bash

cd .github
npm install
npm run docs:dev

Production preview:

bash

npm run docs:build
npm run docs:preview

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

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

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

Симптом	Что проверить
на Pages ломается навигация	`base` в `config.ts`, имя репозитория
локально всё ок, а на Pages пусто	настройки `Settings -> Pages -> GitHub Actions`
часть ассетов не грузится	пути в `public/` и `head`
после изменения sidebar битые ссылки	реальные markdown-файлы и route-paths

Эксплуатационный совет

Документацию лучше поддерживать не “после стабилизации”, а в тот же цикл изменений, что и код:

изменили pipeline — обновили architecture и runbook;
изменили env — обновили infra docs;
изменили аналитический смысл экрана — обновили analytics docs;
добавили новый источник — обновили scrape-helper и карту репозиториев.

Так docs остаются рабочим инструментом, а не архивом исторических обещаний.