Nav

docforge.nav

Navigation layer for doc-forge.

The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

---

Workflow

1. Specification – Users define navigation intent in docforge.nav.yml.
2. Resolution – resolve_nav expands patterns and matches them against generated Markdown files.
3. Emission – MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

---

Classes

MkDocsNavEmitter

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

Functions

emit

emit(nav: ResolvedNav) -> list[dict[str, Any]]

Generate a navigation structure for mkdocs.yml.

Parameters:

Name	Type	Description	Default
nav	ResolvedNav	Resolved navigation data describing documentation groups and their associated Markdown files.	required

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.

NavSpec

NavSpec(
    home: str | None,
    groups: dict[str, list[str]],
    icon: dict[str, str] | None = None,
)

Parsed representation of a navigation specification.

A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name	Type	Description
home	str | None	Relative path to the documentation home page (for example index.md).
groups	dict[str, list[str]]	Mapping of navigation group titles to lists of file patterns or glob expressions.
icon		Optional mapping of theme icon entries (for example {"logo": "material/code-tags"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name	Type	Description	Default
home	str | None	Relative path to the home document.	required
groups	dict[str, list[str]]	Mapping of group names to lists of path patterns (glob expressions).	required
icon	dict[str, str] | None	Optional mapping of theme icon entries applied to the generated MkDocs configuration.	None

Functions

all_patterns

all_patterns() -> list[str]

Return all path patterns referenced by the specification.

Returns:

Type	Description
list[str]	list[str]: A list containing the home document (if defined) and all group pattern entries.

load classmethod

load(path: Path) -> NavSpec

Load a navigation specification from a YAML file.

Parameters:

Name	Type	Description	Default
path	Path	Filesystem path to the navigation specification file.	required

Returns:

Name	Type	Description
NavSpec	NavSpec	A NavSpec instance representing the parsed configuration.

Raises:

Type	Description
FileNotFoundError	If the specified file does not exist.
ValueError	If the file contents are not a valid navigation specification.

ResolvedNav

ResolvedNav(
    home: str | None,
    groups: dict[str, list[Path]],
    docs_root: Path | None = None,
)

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name	Type	Description
home	str | None	Relative path to the documentation home page.
groups	dict[str, list[Path]]	Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name	Type	Description	Default
home	str | None	Relative path to the home page within the documentation root.	required
groups	dict[str, list[Path]]	Mapping of group titles to resolved documentation file paths.	required
docs_root	Path | None	Root directory of the documentation source files.	None

Functions

all_files

all_files() -> Iterable[Path]

Iterate over all files referenced by the navigation structure.

Yields:

Name	Type	Description
Path	Iterable[Path]	A documentation file referenced by the navigation, including the home page when defined.

Raises:

Type	Description
RuntimeError	If the home page is defined but the documentation root is not available for resolution.

Functions

build_wiki_nav

build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]

Derive an MkDocs navigation block from a wiki directory.

Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

• index.md at the wiki root becomes the Home entry.
• Page labels are derived from filenames: numeric order prefixes such as 01_ or 02- are stripped, separators are replaced with spaces, and names are title-cased (01_overview.md becomes Overview).
• Subdirectories become nested navigation groups. A nested index.md is rendered as the section root placed first inside the group.
• Only .md files are considered; hidden entries are ignored.

Parameters:

Name	Type	Description	Default
wiki_dir	Path	Path to the hand-written wiki directory, for example docs/wiki.	required

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Navigation entries compatible with the MkDocs nav configuration. The list is empty if the wiki contains no Markdown files.

Raises:

Type	Description
FileNotFoundError	If the wiki directory does not exist.

load_nav_spec

load_nav_spec(path: Path) -> NavSpec

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

Parameters:

Name	Type	Description	Default
path	Path	Path to the navigation specification file.	required

Returns:

Name	Type	Description
NavSpec	NavSpec	A NavSpec instance representing the parsed specification.

Raises:

Type	Description
FileNotFoundError	If the specification file does not exist.
ValueError	If the YAML structure is invalid.

resolve_nav

resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name	Type	Description	Default
spec	NavSpec	Navigation specification describing documentation layout.	required
docs_root	Path	Root directory containing documentation Markdown files.	required

Returns:

Name	Type	Description
ResolvedNav	ResolvedNav	A ResolvedNav instance containing validated navigation paths.

Raises:

Type	Description
FileNotFoundError	If the documentation root does not exist or a navigation pattern does not match any files.