docs: Q&A with Sonnet — UX analysis + nav merge strategy (Phase 1-3 plan)

2026-08-10 13:32:09 +04:00
parent 35aa50f76d
commit 21b92f4631
4 changed files with 616 additions and 0 deletions
@@ -98,3 +98,16 @@ MAN: <service_man>
 6. MAN-секцию: перевести из HTML в читаемый Markdown.
 7. Описания: сделать грамотными, логичными, на русском. Добавить контекст из MAN где уместно.
 8. **Юзер в первую очередь смотрит на: имя переменной, required/default, что делает параметр.** Это должно быть максимально понятно.
+
+## Сборка mkdocs: слияние статического и динамического nav
+
+mkdocs-material не имеет встроенного `!include` для `nav:`. Решение (рекомендовано): расширить Python pre-build шаг в `04_build_and_publish_docs.sh`:
+
+1. `WriteNavFragment()` генерирует `_nav_fragment.yml` с `resources_nav:` (категории + ресурсы)
+2. Python-блок читает `_nav_fragment.yml`, парсит `mkdocs.yml`, вставляет ресурсы в секцию `Ресурсы` внутри `nav:`
+3. Одновременно копирует `30_registry/` в `docs_dir` (чтобы guides не ломались при смене `docs_dir`)
+4. Результат пишется в `.mkdocs.tmp.yml` → `mkdocs build -f .mkdocs.tmp.yml`
+
+Альтернативы (отвергнуты):
+- docs-generator пишет полный mkdocs.yml (слишком хрупко)
+- mkdocs-awesome-pages (не решает проблему merge static+dynamic)