Deterministic Navigation Resolution

Create a helper that builds a MkDocs navigation tree from per-directory nav config files while respecting deterministic resolution priority between explicit pages, explicit directories, and glob patterns.

Capabilities

Page priority over patterns

• When a nav entry lists a page directly and a sibling glob pattern could match the same file, the resolved navigation includes the page once at the position of the explicit entry and excludes it from the pattern expansion. @test

Directory priority over patterns

• When a nav entry inserts a directory and a sibling glob pattern also targets files inside that directory, the resolved navigation nests the directory first, keeps its internal order, and omits duplicates from the pattern expansion. @test

Stable mixed ordering

• For a nav configuration combining explicit pages, explicit directories, and glob patterns at the same level, the resolved navigation is deterministic: explicit pages appear first in their listed order, followed by explicit directories, followed by pattern-generated items. @test

Implementation

@generates

API

from typing import Any, Dict, List

def build_nav(docs_dir: str, config_filename: str = ".nav.yml") -> List[Dict[str, Any]]:
    """
    Construct the navigation for the given docs_dir using the dependency's resolution rules.

    Returns a list of navigation entries where explicit items take precedence over patterns and duplicates are removed.
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Provides deterministic navigation resolution for MkDocs content.