Публикация учебного руководства

Оглавление · Деплой приложения

Руководство доступно на docs.gheilt.mxsource.xyz. Исходники глав находятся в docs/*.md и docs/*.mdx: один набор файлов читается в GitHub и превращается в статический сайт с русской навигацией, локальным поиском и схемами. Рендерер — Next.js и React с output: "export". MDX-компилятор, React и остальные зависимости закреплены в общем pnpm-lock.yaml. Для чтения готового сайта CMS и Node.js не нужны.

Локальный запуск

pnpm install --frozen-lockfile
pnpm docs:dev

Next.js покажет локальный адрес (порт 3002). Для проверки результата сборки:

pnpm docs:build
pnpm docs:preview

Сборка проверяет ссылки между главами. Ссылки за пределы docs ведут к исходникам репозитория в GitHub. Внутренние планы из docs/superpowers доступны через GitHub, но не включаются в навигацию и поиск сайта. Корневая страница читает docs/README.md: отдельной копии оглавления нет. Файлы .mdx поддерживают зарегистрированные React-компоненты; живой пример показывает учебную модель кеша.

Схемы и поиск

На широком экране боковое оглавление использует position: sticky: остаётся в своей колонке, а при прокрутке главы удерживается у верхнего края окна. Высота ограничена 100dvh; длинный список и результаты поиска прокручиваются внутри оглавления. align-self: start предотвращает растягивание элемента Grid, которое мешало бы sticky-позиционированию. На мобильном экране главы открываются через раскрываемое меню над текстом.

Блоки mermaid преобразуются в компонент схемы. Mermaid загружается из собранных ресурсов сайта, без внешнего CDN; используется строгий режим безопасности. Исходный текст схемы остаётся доступен, в том числе без JavaScript. Поиск также локальный: тексты глав передаются React-компоненту вместе с HTML и не отправляются внешней службе.

Публикация

infra/docs/Dockerfile собирает HTML и ресурсы, затем копирует их в небольшой образ Caddy. Контейнер работает с файловой системой только для чтения и слушает порт 8080 внутри общей Docker-сети. Внешний Caddy выдаёт HTTPS на поддомене docs. Неизвестная глава возвращает HTTP 404 с русским текстом.

Workflow .github/workflows/docs.yaml запускается при изменениях документации и её инфраструктуры в main, а также вручную. Он собирает образ, публикует его в GHCR и передаёт digest в release.env. scripts/deploy/docs.sh использует общую блокировку деплоя, проверяет контейнер и HTTPS, сохраняет предыдущий релиз и восстанавливает конфигурацию прокси при ошибке. Приложение отдельно не пересобирается.

Сборка выполняется в GitHub CI. На VPS загружается готовый образ, компилятор и зависимости разработки там не запускаются. Файлы релиза расположены в /opt/gheilt/docs/releases, текущий релиз — /opt/gheilt/docs/current. При откате используйте прежний release.env и Compose.

Упражнение

Добавьте пояснение в главу, запустите сборку и найдите его через поиск в preview. Затем намеренно сломайте внутреннюю ссылку и убедитесь, что сборка прекращается. Верните правильный адрес перед коммитом. Проверьте прямое открытие URL главы и несуществующий URL: HTTP-код ошибки не должен быть 200.

Справочники: статический экспорт Next.js, MDX, статические файлы Caddy.