Distributed Docs Navigation Preview

Build a helper that turns a docs directory containing distributed navigation definition files into the final MkDocs navigation YAML. The helper must delegate navigation resolution to the navigation plugin dependency rather than reimplementing path discovery or ordering logic.

Capabilities

Builds navigation from distributed files

• Given a docs tree with .nav.yml at the root and inside guides/, where the root file lists index.md, guides/, and api/ while the nested file orders quickstart.md, then a section Deep Dive containing deep/overview.md and deep/api.md, generating navigation YAML returns:

  - Home: index.md
  - Guides:
    - Quickstart: guides/quickstart.md
    - Deep Dive:
      - Overview: guides/deep/overview.md
      - API: guides/deep/api.md
  - API Reference: api/index.md

  @test
• When the root definition lists a directory such as tutorials/ that contains intro.md and advanced/index.md but no .nav.yml, the generated YAML still includes that section using default ordering and derived titles:

  - Tutorials:
    - intro.md
    - advanced/index.md

  @test

Custom nav filename

• When invoked with nav_filename="awesome_nav.yml" and the docs tree contains that file name instead of .nav.yml, the generated navigation YAML follows that file and ignores absent default names. @test

Pattern entries and hidden items

• A navigation definition that includes a glob pattern such as guides/**/*.md pulls in matching pages after any explicit items, skips entries marked hidden in the nav file, and avoids duplicating pages that were already explicitly listed. @test

Implementation

@generates

API

from pathlib import Path

def generate_navigation_yaml(docs_dir: Path, nav_filename: str = ".nav.yml") -> str:
    """Return a YAML string representing the resolved navigation for the docs directory."""

Dependencies { .dependencies }

mkdocs-awesome-nav { .dependency }

Builds MkDocs navigation from distributed navigation definition files.

mkdocs { .dependency }

Site generator used to resolve documentation navigation.