Index Title Reporter

A small utility that reports final navigation titles for documentation directories, honoring index-based title resolution and override rules.

Capabilities

Resolve titles from index metadata

• When a directory enables index-based titles, use the title frontmatter from its index.md to name the section; if no metadata exists, fall back to the formatted directory name. @test

Enforce override precedence

• If a directory receives an explicit title in a parent nav entry or its own config file, that title replaces any index-based title; raw directory names take precedence when directory-name preservation is enabled. @test

Inherit and override settings

• Child directories inherit the parent setting for using index titles unless they define their own flag; disabling it locally reverts to the formatted directory name even when ancestors enable it. @test

Implementation

@generates

API

def build_title_report(docs_root: str) -> list[dict[str, str]]:
    """
    Process the documentation tree rooted at docs_root using .nav.yml files and
    return a depth-first list of directories with their final navigation titles.

    Each item must include "path" (relative directory path, dot for root) and
    "title" (resolved navigation title after applying config, inheritance, and
    override rules).
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Provides navigation rebuilding with .nav.yml-driven title resolution.