Выбор стека публикации¶

Эта страница объясняет, почему для книги выбран именно этот стек публикации.

Короткий ответ¶

MkDocs + Material for MkDocs остается сильным выбором для книги с авторством в Markdown и Python-стеком:

низкий порог входа;
быстрая сборка;
отличный поиск и навигация из коробки;
простая публикация в GitHub Pages;
естественная интеграция с uv, ruff и ty.¹²³⁴

При этом экосистема сейчас находится в переходной точке: в этом репозитории стек намеренно зафиксирован на mkdocs<2, чтобы сохранить совместимость с текущими плагинами и темой и не тащить в первую версию книги ненужный миграционный риск.

Канонические сценарии публикации

Стек публикации должен поддерживать три канонических сценария как маршруты чтения, а не только страницы сборки. Триаж обращений поддержки требует быстрой сборки, публикации на GitHub Pages, поиска и навигации, читаемых примеров политик и подтверждений, а также стабильных ссылок на артефакты трасс и оценок. Внутренний ассистент знаний требует авторства с приоритетом Markdown, многоязычных страниц, глоссария и поиска, ссылок на источники и обновлений материалов памяти/поиска без лишнего трения. Координация инцидентов требует строгого шлюза сборки, воспроизводимых команд документации, стабильной навигации к страницам инцидентов и выпусков, видимых различий в стиле журнала изменений и дисциплины миграционного риска.

Почему я не ушел сразу в Astro Starlight¶

Starlight очень хорош, если вам нужны:

MDX и собственные UI-компоненты;
более тяжелая настройка пользовательского интерфейса;
тесная связка с экосистемой Astro.⁵

Но для этой книги сейчас важнее другое:

писать быстро;
публиковать надежно;
держать весь авторский стек в Python;
не усложнять непрерывные проверки и локальную сборку без реальной необходимости.

Поэтому первая версия сделана на MkDocs, а не на Astro.

Принятая технологическая база¶

Базовый стек¶

uv для управления Python, виртуальной средой и группами зависимостей;
MkDocs и Material for MkDocs для генерации сайта;
ruff для статического анализа;
ty как быстрый проверяющий типы инструмент по мере появления Python-утилит в репозитории.

Опциональный исследовательский стек¶

marimo для интерактивных исследовательских ноутбуков;
polars для анализа журналов, трасс и наборов оценочных данных.

В текущем каркасе marimo и polars уже заведены как отдельная группа research, но пока не используются в книге напрямую.

Команды проекта¶

uv sync --group docs --group dev
uv run mkdocs serve
uv run mkdocs build --strict
uv run ruff check .
uvx ty check

Когда стоит мигрировать в Starlight¶

Переход имеет смысл, если в книге появятся:

React/Vue/Svelte-компоненты внутри глав;
много кастомного интерактива;
документационный продукт вместо книги как основной формы.

Пока таких требований нет.