MkDocs Navigation Logging Helper

A utility that rebuilds MkDocs navigation using directory nav files while allowing per-category log level overrides for the navigation plugin.

Capabilities

Apply category log overrides

• Provided log overrides for nav_override, root_title, root_hide, and no_matches are applied to the navigation plugin before nav generation. @test
• When overrides are omitted, the plugin uses its defaults and still builds navigation normally. @test

Handle nav override logging

• If the MkDocs config already contains a nav section, navigation is rebuilt from nav files and a nav override log record is emitted at the configured level. @test
• If the MkDocs config has no nav entries, navigation is built from nav files without producing a nav override log record. @test

Implementation

@generates

API

from typing import Iterable, Mapping, Tuple
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import Files
from mkdocs.structure.nav import Navigation
from logging import LogRecord

def build_navigation_with_logs(
    mkdocs_config: MkDocsConfig,
    files: Files,
    log_level_overrides: Mapping[str, str] | None = None,
) -> Tuple[Navigation, Iterable[LogRecord]]:
    """Rebuild navigation using directory nav files while applying category-specific log level overrides and capturing emitted log records."""

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Provides navigation rebuild from per-directory nav files and configurable log level categories.