Navigation Ignore Inheritance

Create a helper that resolves documentation navigation using per-directory .nav.yml files, focusing on how ignore patterns are inherited and extended across nested folders.

Capabilities

Inherit and extend ignore rules

• Given docs/.nav.yml ignoring drafts/*, with docs/guides/.nav.yml containing $inherit and internal.md, and files docs/index.md, docs/drafts/overview.md, docs/guides/getting-started.md, docs/guides/advanced.md, docs/guides/internal.md, build_nav returns ["index.md", "guides/getting-started.md", "guides/advanced.md"]. @test

Override inherited ignores

• With docs/.nav.yml ignoring drafts/*, docs/tutorials/.nav.yml listing only private/* (no $inherit), and files docs/index.md, docs/tutorials/.nav.yml, docs/tutorials/drafts/intro.md, docs/tutorials/private/setup.md, the navigation still includes tutorials/drafts/intro.md but omits tutorials/private/setup.md. @test

Deep inheritance stacking

• Given docs/.nav.yml ignores *.tmp, docs/api/.nav.yml uses $inherit plus legacy/**, docs/api/v1/.nav.yml uses $inherit plus *.secret.md, and files docs/api/v1/index.md, docs/api/v1/legacy/ref.md, docs/api/v1/guide.md, docs/api/v1/creds.secret.md, the navigation for api/v1 is ["api/v1/index.md", "api/v1/guide.md"]. @test

Implementation

@generates

API

from pathlib import Path
from typing import Iterable

def build_nav(docs_root: Path) -> list[str]:
    """
    Build the navigation for the docs root using per-directory `.nav.yml` files.
    Returns a depth-first, display-order list of page paths relative to docs_root,
    excluding any entries filtered out by ignore rules (including inherited ones).
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Resolve navigation, inheritance, and ignore patterns defined in .nav.yml files. @satisfied-by