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
@@ -0,0 +1,61 @@
+# Ответ Соннета: Как смержить nav (статический + динамический)
+
+**Дата:** 2026-08-10
+**Вопрос:** Как смержить статический `nav:` (руководства) и динамический (43 ресурса по категориям) в mkdocs?
+**Ответчик:** Claude Sonnet
+
+---
+
+## Нет встроенного `!include` в mkdocs
+
+mkdocs-material не имеет нативного механизма подключения внешних YAML-фрагментов в `nav:`. Плагины (monorepo, awesome-pages) решают другие задачи и здесь не помогут.
+
+---
+
+## Три варианта (по убыванию рекомендованности)
+
+### Вариант 1 — Рекомендую: расширить существующий Python pre-build шаг
+
+В `04_build_and_publish_docs.sh` уже есть Python-блок, который пишет `.mkdocs.tmp.yml`. Добавить туда чтение `_nav_fragment.yml` и инъекцию в `nav:`:
+
+```python
+import yaml
+
+nav_fragment_path = Path(docs_dir) / "_nav_fragment.yml" if docs_dir else None
+if nav_fragment_path and nav_fragment_path.exists():
+    fragment = yaml.safe_load(nav_fragment_path.read_text(encoding="utf-8"))
+    resources_nav = fragment.get("resources_nav", [])
+    
+    config = yaml.safe_load(text)
+    for item in config.get("nav", []):
+        if isinstance(item, dict) and "Ресурсы" in item:
+            item["Ресурсы"] = resources_nav
+            break
+    text = yaml.dump(config, allow_unicode=True, default_flow_style=False, sort_keys=False)
+```
+
+**Плюсы:** ноль новых зависимостей, PyYAML уже в окружении, merge в одном месте, статические секции ("Руководства") остаются нетронутыми.
+
+**Предупреждение:** PyYAML при `dump` меняет форматирование (кавычки, отступы) — это нормально для `.mkdocs.tmp.yml`, который никто не читает руками.
+
+### Вариант 2: docs-generator пишет полный mkdocs.yml
+
+Сделать отдельный файл `mkdocs_base.yml` (тема, плагины, CSS, статический nav — без ресурсов), Go-генератор его читает, добавляет ресурсный nav, пишет финальный mkdocs.yml.
+
+**Минус:** Go-генератор становится ответственным за весь mkdocs.yml, сложнее поддерживать структуру темы/плагинов.
+
+### Вариант 3: mkdocs-awesome-pages
+
+Плагин создаёт `.pages` файлы в директориях и управляет порядком через них. Но `nav:` в mkdocs.yml при этом должен быть либо полностью убран, либо включать ресурсы явно — проблему merge не решает.
+
+---
+
+## Дополнительная проблема: guides при смене `docs_dir`
+
+Когда `docs_dir` переключается на `generated/{stand}/docs_llm`, пути вида `30_registry/guides/getting-started.md` в `nav:` ломаются — этих файлов там нет.
+
+**Решение:** в том же Python pre-build шаге скопировать `30_registry` в `$MKDOCS_DOCS_DIR/30_registry/` перед сборкой. Или — убрать guides из профильного nav (оставить только ресурсы).
+
+---
+
+**Итого:** Вариант 1 — минимальные изменения, всё уже на месте. Нужно только расширить существующий Python блок в `04_build_and_publish_docs.sh` примерно на 10 строк + скопировать `30_registry` в `docs_dir`.