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

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.

3.9 KiB Raw Blame History Unescape Escape