Navigation Title Resolution

Build a small utility that previews the resolved navigation titles for a docs tree that uses distributed navigation metadata files. The utility should rely on the dependency to interpret .nav.yml files, directory names, and index.md frontmatter so the returned navigation matches what would be shown in the rendered site.

Capabilities

Custom titles override generated names

• When a directory's .nav.yml provides a title, the resolved navigation uses that value for the section even if the directory name or any index.md metadata differs. @test

Preserve raw directory names on demand

• When .nav.yml enables raw-name preservation for a directory, the section title matches the exact folder name and does not title-case or use metadata-derived titles. @test

Use index metadata for titles when allowed

• When a directory opts into reading index.md metadata for titles and no custom title or preservation rule is present, the navigation title comes from the title field in that frontmatter. @test

Apply title precedence rules

• When multiple title sources are present, explicit custom titles win over other sources, and raw-name preservation wins over index metadata; the utility returns titles in that priority order. @test

Implementation

@generates

API

from pathlib import Path
from typing import Literal

NavEntry = dict[str, str | Literal["section", "page"]]

def build_nav_titles(docs_root: str | Path) -> list[NavEntry]:
    """
    Resolve navigation for the given docs_root using distributed navigation metadata and
    return an ordered list of navigation entries.

    Each entry contains:
    - "title": the final display title for the item
    - "path": the relative path from docs_root to the file or directory
    - "kind": "section" for directories and "page" for Markdown files
    """

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Generates navigation from per-directory metadata files and applies title customization rules.