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

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

Руководство доступно на docs.gheilt.mxsource.xyz. Исходники глав находятся в тематических каталогах docs: один набор Markdown/MDX-файлов читается в репозитории и превращается в статический сайт с русской навигацией, локальным поиском и схемами. Рендерер — 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

Реестр apps/docs/src/lib/chapters.ts связывает раздел, исходный файл и постоянный URL главы. Меню и порядок соседних глав берутся из этого реестра; исторические отчёты имеют отдельную пометку. Части без написанных глав ведут к программе, пустые страницы для них не создаются. Главная читает docs/README.md, а подробная программа — docs/start/curriculum.md.

pnpm --filter @atmanki/docs test
pnpm --filter @atmanki/docs typecheck

Node test runner проверяет полноту реестра, уникальность адресов и ссылки между разделами. Общий с рендерером разбор MDX через remark-gfm и rehype-slug собирает настоящие heading IDs: проверяются ссылки на другие главы и якоря текущей страницы, включая повторяющиеся заголовки и кириллицу. Ссылки на исходники проверяются по файлам и каталогам repository; отсутствующий файл не превращается в правдоподобный browse URL. Примеры ссылок внутри блоков кода не считаются переходами. Тесты запускаются также перед сборкой документационного образа. В package.json указан ESM; allowImportingTsExtensions позволяет typecheck проверять нативные Node-тесты с импортами .ts, не меняя сборку Next.js.

При добавлении главы зарегистрируйте её файл и URL в реестре. При переносе файла сохраните slug и исправьте относительные ссылки; URL сайта не зависит от каталога. Проверки обнаруживают незарегистрированные публичные MD/MDX.

При загрузке документов рендерер выполняет ту же проверку всего реестра, поэтому сломанная ссылка останавливает и сборку, и локальный preview. Ссылки за пределы docs ведут к исходникам репозитория в SourceCraft (/browse/PATH?rev=main). Внутренние планы из docs/superpowers доступны там же, но не включаются в навигацию и поиск сайта. Файлы .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 с русским текстом.

Build stage получает также исходники, на которые ссылаются главы, чтобы проверка существования repository targets работала внутри CI. Packaging-тест сверяет COPY и правила Docker context с реальными ссылками. Для двух исторических сравнений разрешены только четыре уже опубликованных файла просмотрщиков и измерений; локальные screenshots, .env, credentials и соседние worktree исключены. В готовый runtime image копируются только HTML и ресурсы статического экспорта.

Документационный образ входит в четыре application images .sourcecraft/ci.yaml. CI публикует его в YC Registry; VPS получает готовый digest по HTTPS. Main обновляет test, release/X.Y — staging, а опубликованный native stable Release продвигает те же образы на production. Docs переключаются вместе с web, CMS и Storybook через blue-green transaction. Отдельный GitHub workflow удалён. На VPS не запускаются компилятор и зависимости разработки.

Упражнение

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

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