# Ответ Соннета: Как смержить 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`.