Docs Navigation Harmonizer

Build a small utility that uses the navigation plugin to compute the final MkDocs nav for a docs directory while leveraging automatic flattening of single-child sections and appending of otherwise unmatched files.

Capabilities

Flatten single-child directories

• With flattening enabled at the root, a directory that contains exactly one visible page becomes a single nav entry pointing to that page instead of a nested section; directories with multiple items stay grouped. @test

Respect local opt-outs

• When a child .nav.yml disables flattening, that directory remains a section even if it has only one visible page, while the root flattening still applies elsewhere. @test

Append unmatched content

• When nav entries omit certain files or subdirectories, turning on automatic appending adds those unmatched items to the end of the parent section using the plugin’s normal ordering. @test

Implementation

Enable flattening and automatic appending at the root by default, allow overrides via root_config, and rely on the plugin to resolve .nav.yml files instead of rebuilding the rules by hand.

@generates

API

from pathlib import Path
from typing import Any

def build_nav(docs_dir: Path, root_config: dict[str, Any] | None = None) -> list[dict[str, Any]]:
    """
    Build the final MkDocs nav for the given docs directory using the navigation plugin,
    honoring flatten-single-child behavior and automatic appending of unmatched files, with root
    defaults that turn both behaviors on unless explicitly overridden by root_config.
    Returns the nav structure as a list of dictionaries mirroring MkDocs config.
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Rebuilds MkDocs navigation from per-directory nav files, including flattening and automatic append behaviors.