Вывод
Рекомендуемый стек
Предметная область — исследования доступности городской среды (маршрутизация для пользователей колясок,
открытые геоданные). Результаты здесь — таблицы и графики, пересчитываемые из CSV и выгрузок OSM.
Сложной математики и длинных доказательств почти нет, зато есть частые обновления данных и требования к открытости.
| Слой |
Выбор |
Почему |
| Генератор |
MkDocs 1.6 + Material 9.7 |
Markdown, хороший русский поиск (lunr + стеммер), сетки и карточки, overrides без форка темы, хуки на Python |
| Пакеты |
uv + pyproject.toml + uv.lock, Python из .python-version |
воспроизводимость на чистом раннере, uv sync --frozen за 0,3 с из кэша |
| Данные → страница |
MkDocs-хук (on_pre_build), CSV → Markdown-таблицы и PNG |
нет отдельного шага в CI, mkdocs serve пересчитывает при правке данных, метка версии данных в подвале |
| Формулы и шрифты |
MathJax и шрифты локально (privacy + размещённый MathJax) |
сайт не зависит от CDN: +4 % веса, на 10 внешних запросов меньше |
| Основная площадка |
GitHub Pages через deploy-pages |
самые узкие права токена, CDN, HTTPS, нулевое обслуживание |
| Зеркало в РФ |
Helios через SSH/rsync с ключом, ограниченным шлюзом |
доступность из российских сетей, preview веток, откат за секунды |
| Безопасность CI |
SHA-пиннинг actions, build без секретов, минимальные permissions, known_hosts из секрета |
см. T4 |
Когда рекомендация меняется
| Условие |
Что выбрать вместо |
| Нужны нумерация уравнений и рисунков, перекрёстные ссылки, BibTeX, PDF из того же источника |
Quarto или Sphinx + MyST (Jupyter Book 2 / MyST) |
| Результаты — Jupyter-ноутбуки, которые нужно исполнять при сборке |
MyST-NB / Jupyter Book с кэшем исполнения, или Quarto freeze |
| Вычисления тяжелее лимитов CI (GPU, часы) |
расчёт вне CI, в репозиторий — готовые артефакты с хешем данных и коммита; CI только собирает сайт |
| Раннеры GitHub перестанут достигать Helios (фильтрация по адресу, см. Отладку) |
self-hosted runner в сети ИТМО или CI на отечественной платформе (GitVerse, SourceCraft) |
| Публикация должна быть цитируемой (DOI, архивирование) |
GitHub Release + Zenodo, версии сайта через mike, метаданные Highwire/Dublin Core |
| Долгосрочная поддержка важнее богатства плагинов |
Material предупреждает, что MkDocs 2.0 несовместим с плагинами и темами. Нужно зафиксировать MkDocs 1.6 в uv.lock (уже сделано) и следить за Zensical — преемником от авторов Material |
| Хостинг без SSH (только объектное хранилище) |
загрузка по S3 API ключом с ролью storage.uploader на один бакет; откат — версионирование объектов бакета |
Ограничения этой работы
- Helios: деплой с раннеров GitHub проверен на уровне сети (
helios-probe). Время доставки на Helios
приведено в P4 по результатам реальных запусков.
- Вес страницы измерен на одной странице (
results/), Chromium 153, без кэша браузера.
- Оценка «с gzip» — расчётная (gzip уровня 6 для текстовых ресурсов), так как локальный
http.server не сжимает ответы.