mkdocs cli

docforge/nav/__init__.py

@@ -1,4 +1,4 @@
-from .spec import NavSpec
+from .spec import NavSpec, load_nav_spec
 from .resolver import ResolvedNav, resolve_nav
 from .mkdocs import MkDocsNavEmitter
 
@@ -7,4 +7,5 @@ __all__ = [
     "ResolvedNav",
     "MkDocsNavEmitter",
     "resolve_nav",
+    "load_nav_spec",
 ]

docforge/nav/__init__.pyi

@@ -1,4 +1,4 @@
-from .spec import NavSpec
+from .spec import NavSpec, load_nav_spec
 from .resolver import ResolvedNav, resolve_nav
 from .mkdocs import MkDocsNavEmitter
 
@@ -7,4 +7,5 @@ __all__ = [
     "ResolvedNav",
     "MkDocsNavEmitter",
     "resolve_nav",
+    "load_nav_spec",
 ]

docforge/nav/mkdocs.py

@@ -1,24 +1,34 @@
 from __future__ import annotations
 
-from typing import Any, Dict, List
+from pathlib import Path
+from typing import List, Dict, Any
 
 from docforge.nav.resolver import ResolvedNav
 
 
 class MkDocsNavEmitter:
-    """Emit MkDocs-compatible nav structure."""
+    """Emit MkDocs-compatible nav structures."""
 
     def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
         result: List[Dict[str, Any]] = []
 
+        # Home entry (semantic path)
         if nav.home:
             result.append({"Home": nav.home})
 
+        # Group entries
         for group, paths in nav.groups.items():
-            entries: List[Dict[str, str]] = []
-            for path in paths:
-                title = path.stem.replace("_", " ").title()
-                entries.append({title: path.as_posix()})
+            entries: List[str] = []
+            for p in paths:
+                # Convert filesystem path back to docs-relative path
+                entries.append(self._to_relative(p))
             result.append({group: entries})
 
         return result
+
+    def _to_relative(self, path: Path) -> str:
+        """
+        Convert a filesystem path to a docs-relative path.
+        """
+        # Normalize to POSIX-style for MkDocs
+        return path.as_posix().split("/docs/", 1)[-1]

docforge/nav/mkdocs.pyi

@@ -1,4 +1,5 @@
 from typing import Dict, List, Any
+from pathlib import Path
 
 from docforge.nav.resolver import ResolvedNav
 
@@ -25,3 +26,9 @@ class MkDocsNavEmitter:
         ]
         """
         ...
+
+    def _to_relative(self, path: Path) -> str:
+        """
+        Convert a filesystem path to a docs-relative path.
+        """
+        ...

docforge/nav/spec.py

@@ -53,3 +53,17 @@ class NavSpec:
         for items in self.groups.values():
             patterns.extend(items)
         return patterns
+
+
+def load_nav_spec(path: Path) -> NavSpec:
+    if not path.exists():
+        raise FileNotFoundError(path)
+
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Nav spec must be a YAML mapping")
+
+    return NavSpec(
+        home=data.get("home"),
+        groups=data.get("groups", {}),
+    )

docforge/nav/spec.pyi

@@ -13,6 +13,13 @@ class NavSpec:
     home: Optional[str]
     groups: Dict[str, List[str]]
 
+    def __init__(
+        self,
+        home: Optional[str],
+        groups: Dict[str, List[str]],
+    ) -> None:
+        ...
+
     @classmethod
     def load(cls, path: Path) -> "NavSpec":
         """
@@ -30,3 +37,6 @@ class NavSpec:
         (including home and group entries).
         """
         ...
+
+
+def load_nav_spec(path: Path) -> NavSpec: ...