Pattern-Driven Navigation Builder

Assemble a MkDocs-style navigation structure by expanding explicit entries and glob patterns while ensuring no page or directory appears more than once.

Capabilities

Expands globbed rules into navigation

• Given docs_root containing index.md, guide/setup.md, and guide/configure.md, and rules where index.md is explicit and guide/*.md is a pattern grouped under "Guides", navigation returns Home first and then Guides with configure before setup, all paths relative to docs_root and grouped as [{'title': 'Home', 'path': 'index.md'}, {'title': 'Guides', 'children': [{'title': 'configure', 'path': 'guide/configure.md'}, {'title': 'setup', 'path': 'guide/setup.md'}]}] @test

Avoids duplicates across explicit and pattern matches

• When guide/setup.md is listed explicitly before a guide/*.md pattern, the resulting navigation places setup in its explicit position and omits it from the pattern-generated children even though it matches the glob @test

Warns on empty matches when not suppressed

• Invoking navigation build with warn_on_empty=True and a pattern guides/**/*.md against a tree with no guides directory records a warning describing the missing matches; repeating the call with the same rule marked as suppress_warning yields no warnings @test

Implementation

@generates

API

from dataclasses import dataclass
from pathlib import Path
from typing import Sequence

@dataclass
class PatternRule:
    """Definition of a nav entry coming from an explicit path or a glob pattern."""
    title: str
    path: str | None = None  # explicit file or directory path relative to docs_root
    pattern: str | None = None  # glob rule relative to docs_root
    suppress_warning: bool = False  # prevents recording a warning when pattern has no matches

@dataclass
class NavResult:
    nav: list[dict]
    warnings: list[str]


def build_navigation(docs_root: Path, rules: Sequence[PatternRule], *, warn_on_empty: bool = True) -> NavResult:
    """
    Build a MkDocs navigation list using explicit entries and glob patterns.

    - Explicit rules appear in the provided order.
    - Pattern rules expand recursive glob expressions relative to docs_root, group matches under the rule's title, and sort children alphabetically by relative path.
    - Child titles default to the stem of the matched file or directory.
    - A page or directory matched by multiple rules appears only once, preferring the first explicit or pattern occurrence.
    - When warn_on_empty is True and a pattern finds no matches without suppress_warning, a warning string referencing that pattern is recorded.
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

MkDocs navigation plugin that expands glob rules and prevents duplicate nav entries.