Skip to content

Commit fc64335

Browse files
committed
ci(docs): check that page URLs match their file paths
Signed-off-by: Johnny Greco <jogreco@nvidia.com>
1 parent b072ebc commit fc64335

8 files changed

Lines changed: 424 additions & 2 deletions

File tree

‎.agents/skills/update-docs/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ Write the doc update following the rules in `docs/CONTRIBUTING.mdx`. Key reminde
108108
- **Use `sidebar-title` for short nav labels**. For explicit navigation entries, keep relative `slug` values in `docs/index.yml` instead of page frontmatter.
109109
- **Keep explicit `page:` entries in `docs/index.yml`**. Fern still requires them. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the page frontmatter `title`.
110110
- **Use `skip-slug: true` in `docs/index.yml`** when a child page should live at the parent section path.
111+
- **Keep each page URL equal to its file path** under `docs/`. Rename the file when you rename a page, add a `fern/docs.yml` redirect for the old URL, and set a relative `slug:` when the nav label does not produce the file name. `mise run docs` runs `docs:nav`, which fails otherwise.
111112
- **Use `keywords` as a comma-separated string**.
112113
- **Do not add a duplicate H1**. Fern renders the page title from frontmatter.
113114
- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.

‎.github/workflows/branch-docs.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
- "fern/**"
88
- "mise.toml"
99
- "tasks/docs.toml"
10+
- "tasks/scripts/check_docs_nav.py"
1011
- ".github/workflows/branch-docs.yml"
1112
- ".github/workflows/release-tag.yml"
1213

@@ -47,6 +48,15 @@ jobs:
4748
working-directory: ./fern
4849
run: fern check
4950

51+
- name: Install uv
52+
uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
53+
with:
54+
version: "0.10.12"
55+
python-version: "3.13"
56+
57+
- name: Check docs navigation matches file paths
58+
run: uv run tasks/scripts/check_docs_nav.py
59+
5060
- name: Generate preview URL
5161
if: ${{ steps.fern-preview.outputs.enabled == 'true' }}
5262
id: generate-docs

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -487,7 +487,7 @@ field design, and schema-evolution rules.
487487

488488
## Documentation
489489

490-
If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR and adjust `docs/index.yml` if navigation changes. For explicit navigation entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `docs/index.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides.
490+
If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR and adjust `docs/index.yml` if navigation changes. For explicit navigation entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `docs/index.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides. Keep every page URL equal to its file path under `docs/`; `mise run docs` checks this with `docs:nav`.
491491

492492
To ensure your doc changes follow NVIDIA documentation style, use the `update-docs-from-commits` skill.
493493
It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `docs/CONTRIBUTING.mdx`.

‎docs/CONTRIBUTING.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,8 @@ keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing"
8989

9090
For explicit entries in `docs/index.yml`, keep `page:`. Fern still requires it. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the frontmatter `title`.
9191

92+
Keep every page URL equal to its file path under `docs/`, without `.mdx`. Fern builds URLs from nav labels and slugs, not from file paths, so rename the file when you rename a page, and add a redirect in `fern/docs.yml` for the old URL. When a nav label does not produce the file name, for example `TypeScript`, which Fern turns into `type-script`, set a relative `slug:` on the entry in `docs/index.yml`. `mise run docs` runs `mise run docs:nav`, which fails when a page URL differs from its file path, when a nav label differs from the page's sidebar name, when a page is missing from the navigation, or when a redirect points to a page that does not exist.
93+
9294
### Page Structure
9395

9496
1. Frontmatter `title` and `description`, plus any relevant page metadata.

‎tasks/docs.toml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
["docs"]
77
description = "Validate Fern documentation"
8-
depends = ["docs:build:strict"]
8+
depends = ["docs:build:strict", "docs:nav"]
99

1010
["docs:deps"]
1111
description = "Resolve Fern CLI for docs tasks"
@@ -23,6 +23,10 @@ cd fern
2323
npx --yes "fern-api@${FERN_VERSION}" check
2424
"""
2525

26+
["docs:nav"]
27+
description = "Check that docs page URLs match their file paths"
28+
run = "uv run tasks/scripts/check_docs_nav.py"
29+
2630
["docs:serve"]
2731
description = "Serve Fern docs locally"
2832
depends = ["docs:deps"]

‎tasks/scripts/check_docs_nav.py‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
#!/usr/bin/env python3
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
# /// script
6+
# requires-python = ">=3.9"
7+
# dependencies = [
8+
# "PyYAML==6.0.2",
9+
# ]
10+
# ///
11+
12+
"""Check that the published docs navigation mirrors the docs folder structure.
13+
14+
Fern does not build page URLs from file paths. It uses, in order, the page's
15+
frontmatter `slug`, the nav entry's `slug`, or the nav label, and it splits
16+
camel case in labels, so "TypeScript" becomes `type-script`. Pages in a
17+
`folder:` section use their file names. A URL can therefore drift away from
18+
where its file lives without any link breaking.
19+
20+
This check fails when:
21+
22+
- a page's URL differs from its file path under docs/, without `.mdx`, and
23+
without `/index` for a section's own page;
24+
- a nav page's sidebar name, its `sidebar-title` or else its `title`, differs
25+
from its nav label. Fern shows the sidebar name but builds the URL from the
26+
label, so the two must agree;
27+
- a docs page is not reachable from the navigation; or
28+
- a redirect for this docs version points to a URL that does not exist, or its
29+
source is still a live page.
30+
"""
31+
32+
from __future__ import annotations
33+
34+
import argparse
35+
import re
36+
import sys
37+
from dataclasses import dataclass, field
38+
from pathlib import Path
39+
40+
import yaml
41+
42+
# Files under docs/ that are intentionally not published as pages.
43+
UNPUBLISHED = {"CONTRIBUTING.mdx"}
44+
45+
46+
def fern_slug(label: str) -> str:
47+
"""Slugify a nav label the way Fern does, including camel-case splits."""
48+
split = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", label)
49+
return re.sub(r"[^a-z0-9]+", "-", split.lower()).strip("-")
50+
51+
52+
def path_url(rel_path: str) -> str:
53+
"""Return the URL that a docs file path implies."""
54+
url = "/" + re.sub(r"\.mdx$", "", rel_path)
55+
return re.sub(r"/index$", "", url)
56+
57+
58+
def frontmatter(path: Path) -> dict:
59+
match = re.match(r"---\n(.*?)\n---", path.read_text(encoding="utf-8"), re.S)
60+
if not match:
61+
return {}
62+
return yaml.safe_load(match.group(1)) or {}
63+
64+
65+
@dataclass
66+
class NavCheck:
67+
docs_root: Path
68+
urls: dict[str, str] = field(default_factory=dict) # URL -> docs-relative path
69+
reachable: set[str] = field(default_factory=set)
70+
issues: list[str] = field(default_factory=list)
71+
72+
def page_url(self, rel_path: str, default_url: str) -> str:
73+
slug = frontmatter(self.docs_root / rel_path).get("slug")
74+
return "/" + str(slug).strip("/") if slug else default_url
75+
76+
def record(self, rel_path: str, url: str, how: str) -> None:
77+
self.reachable.add(rel_path)
78+
if url in self.urls and self.urls[url] != rel_path:
79+
self.issues.append(
80+
f"{rel_path}: URL {url} is also used by {self.urls[url]}"
81+
)
82+
self.urls[url] = rel_path
83+
expected = path_url(rel_path)
84+
if url != expected:
85+
self.issues.append(
86+
f"{rel_path}: URL {url} ({how}) does not match its file path "
87+
f"{expected}. Rename the file, change the nav label, or set "
88+
f'frontmatter slug: "{expected.lstrip("/")}".'
89+
)
90+
91+
def walk(self, items: list, prefix: str) -> None:
92+
for item in items or []:
93+
if "section" in item:
94+
url = prefix + "/" + item.get("slug", fern_slug(item["section"]))
95+
if "path" in item:
96+
rel = item["path"]
97+
self.record(rel, self.page_url(rel, url), "section page")
98+
self.walk(item.get("contents", []), url)
99+
elif "page" in item:
100+
rel, label = item["path"], item["page"]
101+
if not (self.docs_root / rel).exists():
102+
self.issues.append(
103+
f"docs/index.yml: nav page {label!r} points to missing {rel}"
104+
)
105+
continue
106+
if "slug" in item:
107+
default, how = prefix + "/" + item["slug"], "nav slug"
108+
else:
109+
default, how = (
110+
prefix + "/" + fern_slug(label),
111+
f"nav label {label!r}",
112+
)
113+
meta = frontmatter(self.docs_root / rel)
114+
how = "frontmatter slug" if meta.get("slug") else how
115+
self.record(rel, self.page_url(rel, default), how)
116+
shown_key = "sidebar-title" if "sidebar-title" in meta else "title"
117+
shown = meta.get(shown_key)
118+
if shown != label:
119+
self.issues.append(
120+
f"{rel}: {shown_key} {shown!r} does not match nav label {label!r}"
121+
)
122+
elif "folder" in item:
123+
folder = item["folder"].strip("./").rstrip("/")
124+
url = (
125+
prefix
126+
+ "/"
127+
+ item.get("slug", fern_slug(item.get("title", folder)))
128+
)
129+
for page in sorted((self.docs_root / folder).rglob("*.mdx")):
130+
rel = page.relative_to(self.docs_root).as_posix()
131+
stem = (
132+
page.relative_to(self.docs_root / folder)
133+
.with_suffix("")
134+
.as_posix()
135+
)
136+
default = re.sub(r"/index$", "", url + "/" + stem)
137+
how = (
138+
"frontmatter slug"
139+
if frontmatter(page).get("slug")
140+
else "folder file name"
141+
)
142+
self.record(rel, self.page_url(rel, default), how)
143+
144+
def check_orphans(self) -> None:
145+
for page in sorted(self.docs_root.rglob("*.mdx")):
146+
rel = page.relative_to(self.docs_root).as_posix()
147+
if rel in UNPUBLISHED or rel in self.reachable or rel.startswith("_"):
148+
continue
149+
self.issues.append(f"{rel}: not reachable from docs/index.yml")
150+
151+
def check_redirects(self, redirects: list, prefix: str) -> None:
152+
live = set(self.urls) | {""}
153+
for redirect in redirects or []:
154+
source, dest = redirect.get("source", ""), redirect.get("destination", "")
155+
if dest.startswith(prefix + "/") or dest == prefix:
156+
target = dest[len(prefix) :].split("#", 1)[0].rstrip("/")
157+
if ":" not in target and target not in live:
158+
self.issues.append(
159+
f"fern/docs.yml: redirect {source} -> {dest}: destination does not exist"
160+
)
161+
if source.startswith(prefix + "/") and ":" not in source:
162+
origin = source[len(prefix) :].rstrip("/")
163+
if origin in live:
164+
self.issues.append(
165+
f"fern/docs.yml: redirect source {source} is still a live page"
166+
)
167+
168+
169+
def redirect_prefix(fern_config: dict, nav_file: Path, config_dir: Path) -> str | None:
170+
"""Return the URL prefix, such as /openshell/dev, for the checked docs version."""
171+
instances = fern_config.get("instances") or []
172+
url = instances[0].get("url", "") if instances else ""
173+
base = "/" + url.split("/", 1)[1].strip("/") if "/" in url else ""
174+
for version in fern_config.get("versions") or []:
175+
if (config_dir / version.get("path", "")).resolve() == nav_file.resolve():
176+
return f"{base}/{version['slug']}".replace("//", "/")
177+
return None
178+
179+
180+
def run(repo_root: Path) -> list[str]:
181+
docs_root = repo_root / "docs"
182+
nav_file = docs_root / "index.yml"
183+
nav = yaml.safe_load(nav_file.read_text(encoding="utf-8"))
184+
check = NavCheck(docs_root)
185+
landing = (nav.get("landing-page") or {}).get("path")
186+
if landing:
187+
check.reachable.add(landing)
188+
check.walk(nav.get("navigation", []), "")
189+
check.check_orphans()
190+
fern_file = repo_root / "fern" / "docs.yml"
191+
if fern_file.exists():
192+
fern_config = yaml.safe_load(fern_file.read_text(encoding="utf-8"))
193+
prefix = redirect_prefix(fern_config, nav_file, fern_file.parent)
194+
if prefix:
195+
check.check_redirects(fern_config.get("redirects"), prefix)
196+
return check.issues
197+
198+
199+
def main() -> int:
200+
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
201+
parser.add_argument(
202+
"--repo-root", type=Path, default=Path(__file__).resolve().parents[2]
203+
)
204+
args = parser.parse_args()
205+
issues = run(args.repo_root)
206+
for issue in issues:
207+
print(f"docs nav: {issue}", file=sys.stderr)
208+
if issues:
209+
print(f"docs nav: {len(issues)} problem(s) found", file=sys.stderr)
210+
return 1
211+
print("docs nav: every page URL matches its file path")
212+
return 0
213+
214+
215+
if __name__ == "__main__":
216+
sys.exit(main())

0 commit comments

Comments
 (0)