fix(docs): align navigation checks with repo conventions

Signed-off-by: Johnny Greco <jogreco@nvidia.com>

Author: johnnygreco

.github/workflows/branch-docs.yml

@@ -7,7 +7,9 @@ on:
       - "fern/**"
       - "mise.toml"
       - "tasks/docs.toml"
+      - "tasks/test.toml"
       - "tasks/scripts/check_docs_nav.py"
+      - "tasks/scripts/check_docs_nav_test.py"
       - ".github/workflows/branch-docs.yml"
       - ".github/workflows/release-tag.yml"
 
@@ -54,6 +56,9 @@ jobs:
           version: "0.10.12"
           python-version: "3.13"
 
+      - name: Test docs navigation check
+        run: uv run --no-project --with pytest --with pytest-asyncio --with pyyaml pytest tasks/scripts/check_docs_nav_test.py
+
       - name: Check docs navigation matches file paths
         run: uv run tasks/scripts/check_docs_nav.py
 

architecture/build.md

@@ -584,8 +584,10 @@ See `CI.md` for the contributor workflow, labels, and maintainer merge-queue wor
 Published docs live in `docs/`. Navigation lives in `docs/index.yml`. Fern site
 configuration, components, theme assets, and publish settings live in `fern/`.
 
-Use `mise run docs` for strict validation and `mise run docs:serve` for local
-preview. PR previews are produced by `.github/workflows/branch-docs.yml` when
+Use `mise run docs` for Fern validation and navigation-to-file-path consistency,
+and `mise run docs:serve` for local preview. The docs PR workflow also runs the
+navigation check's unit tests (`mise run test:docs-nav`).
+PR previews are produced by `.github/workflows/branch-docs.yml` when
 Fern credentials are available. Production docs publish from the release tag
 workflow.
 

tasks/scripts/check_docs_nav.py

@@ -84,14 +84,17 @@ def record(self, rel_path: str, url: str, how: str) -> None:
         if url != expected:
             self.issues.append(
                 f"{rel_path}: URL {url} ({how}) does not match its file path "
-                f"{expected}. Rename the file, change the nav label, or set "
-                f'frontmatter slug: "{expected.lstrip("/")}".'
+                f"{expected}. Rename the file, change the nav label, or set a "
+                "relative slug in docs/index.yml. For folder-discovered pages, "
+                f'use frontmatter slug: "{expected.lstrip("/")}".'
             )
 
     def walk(self, items: list, prefix: str) -> None:
         for item in items or []:
             if "section" in item:
                 url = prefix + "/" + item.get("slug", fern_slug(item["section"]))
+                if item.get("skip-slug"):
+                    url = prefix
                 if "path" in item:
                     rel = item["path"]
                     self.record(rel, self.page_url(rel, url), "section page")
@@ -103,7 +106,9 @@ def walk(self, items: list, prefix: str) -> None:
                         f"docs/index.yml: nav page {label!r} points to missing {rel}"
                     )
                     continue
-                if "slug" in item:
+                if item.get("skip-slug"):
+                    default, how = prefix, "skip-slug"
+                elif "slug" in item:
                     default, how = prefix + "/" + item["slug"], "nav slug"
                 else:
                     default, how = (
@@ -126,6 +131,8 @@ def walk(self, items: list, prefix: str) -> None:
                     + "/"
                     + item.get("slug", fern_slug(item.get("title", folder)))
                 )
+                if item.get("skip-slug"):
+                    url = prefix
                 for page in sorted((self.docs_root / folder).rglob("*.mdx")):
                     rel = page.relative_to(self.docs_root).as_posix()
                     stem = (
@@ -197,7 +204,9 @@ def run(repo_root: Path) -> list[str]:
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser = argparse.ArgumentParser(
+        description="Check that the published docs navigation mirrors the docs folder structure."
+    )
     parser.add_argument(
         "--repo-root", type=Path, default=Path(__file__).resolve().parents[2]
     )

tasks/scripts/check_docs_nav_test.py

@@ -3,20 +3,14 @@
 
 from __future__ import annotations
 
-import importlib.util
-import sys
 import textwrap
-from pathlib import Path
+from typing import TYPE_CHECKING
 
+import check_docs_nav
 import pytest
 
-SPEC = importlib.util.spec_from_file_location(
-    "check_docs_nav", Path(__file__).with_name("check_docs_nav.py")
-)
-check_docs_nav = importlib.util.module_from_spec(SPEC)
-sys.modules[SPEC.name] = check_docs_nav
-assert SPEC.loader is not None
-SPEC.loader.exec_module(check_docs_nav)
+if TYPE_CHECKING:
+    from pathlib import Path
 
 FERN_CONFIG = """\
 instances:
@@ -97,7 +91,7 @@ def test_label_url_that_differs_from_file_path_fails(tmp_path: Path) -> None:
     issues = check_docs_nav.run(root)
     assert len(issues) == 1
     assert "URL /sdk/type-script" in issues[0]
-    assert 'slug: "sdk/typescript"' in issues[0]
+    assert "relative slug in docs/index.yml" in issues[0]
 
 
 def test_frontmatter_slug_can_pin_the_url_to_the_file_path(tmp_path: Path) -> None:
@@ -135,6 +129,70 @@ def test_sidebar_name_must_match_nav_label(tmp_path: Path) -> None:
     ]
 
 
+@pytest.mark.parametrize(
+    ("nav", "rel"),
+    [
+        (
+            """
+            navigation:
+            - section: Guides
+              slug: ignored
+              skip-slug: true
+              contents:
+              - page: Setup
+                path: setup.mdx
+            """,
+            "setup.mdx",
+        ),
+        (
+            """
+            navigation:
+            - section: Guides
+              contents:
+              - page: Setup
+                slug: ignored
+                skip-slug: true
+                path: guides/index.mdx
+            """,
+            "guides/index.mdx",
+        ),
+        (
+            """
+            navigation:
+            - section: Guides
+              contents:
+              - folder: guides
+                slug: ignored
+                skip-slug: true
+            """,
+            "guides/setup.mdx",
+        ),
+    ],
+)
+def test_skip_slug_omits_navigation_level(tmp_path: Path, nav: str, rel: str) -> None:
+    root = build(tmp_path, nav, {rel: page("Setup")})
+    assert check_docs_nav.run(root) == []
+
+
+def test_skip_slug_detects_url_that_differs_from_file_path(tmp_path: Path) -> None:
+    root = build(
+        tmp_path,
+        """
+        navigation:
+        - section: Guides
+          skip-slug: true
+          contents:
+          - page: Setup
+            path: guides/setup.mdx
+        """,
+        {"guides/setup.mdx": page("Setup")},
+    )
+    issues = check_docs_nav.run(root)
+    assert len(issues) == 1
+    assert "URL /setup" in issues[0]
+    assert "does not match its file path /guides/setup" in issues[0]
+
+
 def test_folder_pages_use_file_names_and_orphans_fail(tmp_path: Path) -> None:
     root = build(
         tmp_path,

tasks/test.toml

@@ -31,7 +31,7 @@ run = "uv run --no-project --with pytest --with pytest-asyncio --with pyyaml pyt
 
 ["test:docs-nav"]
 description = "Test the docs navigation check"
-run = "uv run --no-project --with pytest --with pyyaml pytest tasks/scripts/check_docs_nav_test.py"
+run = "uv run --no-project --with pytest --with pytest-asyncio --with pyyaml pytest tasks/scripts/check_docs_nav_test.py"
 
 ["test:sbom"]
 description = "Run SBOM tooling tests"