fix(docs): resolve Fern routes in link checker by cv · Pull Request #4688 · NVIDIA/NemoClaw

cv · 2026-06-02T23:39:24Z

Summary

Update the docs link checker so it validates Fern-style routes instead of treating extensionless MDX and variant-navigation links as broken filesystem paths. This fixes docs-validation failures after the Fern migration while keeping local link validation active.

Changes

Build a lightweight route index from docs/index.yml during check-docs.sh link validation.
Resolve extensionless .md / .mdx links, route-relative Fern links, and OpenClaw/Hermes variant routes.
Add regression tests for Fern variant routes, route-relative links, and nav slugs that differ from source file paths.

Type of Change

Code change (feature, bug fix, or refactor)
Code change with doc updates
Doc only (prose changes, no code sample modifications)
Doc only (includes code sample changes)

Verification

npx prek run --all-files passes
npm test passes
Tests added or updated for new or changed behavior
No secrets, API keys, or credentials committed
Docs updated for user-facing behavior changes
npm run docs builds without warnings (doc changes only)
Doc pages follow the style guide (doc changes only)
New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Tests
- Added end-to-end tests verifying documentation link rewriting and that local docs and site-route links resolve; includes checks that failures are reported for broken or unbuildable site routes.
Chores
- Enhanced the docs link checker to resolve site-route-style links, normalize varied path formats, and more reliably detect missing or misreferenced documentation pages.

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

coderabbitai · 2026-06-02T23:39:35Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4d31585c-5d9e-4e98-b719-a480807e7425

📥 Commits

Reviewing files that changed from the base of the PR and between 8642907 and 3bd5a5a.

📒 Files selected for processing (2)

test/check-docs-links.test.ts
test/e2e/e2e-cloud-experimental/check-docs.sh

🚧 Files skipped from review as they are similar to previous changes (1)

test/e2e/e2e-cloud-experimental/check-docs.sh

📝 Walkthrough

Walkthrough

Docs link checker now resolves Fern site routes by lazily indexing docs navigation, adds normalization and source-existence helpers, integrates Fern-route checks into local-ref resolution and logging, and adds Vitest tests for successful rewriting and failure modes when routes or the route index are invalid.

Changes

Fern route link resolution

Layer / File(s)	Summary
Fern route indexing and helper functions `test/e2e/e2e-cloud-experimental/check-docs.sh`	Added cached globals and a lazy loader that parses `docs/index.yml` via an embedded Node snippet and builds a route index; implemented `normalize_fern_route_path`, `fern_route_exists`, `fern_relative_ref_exists`, `source_ref_exists`, and `site_source_ref_exists`.
Local ref resolution with Fern routes and logging `test/e2e/e2e-cloud-experimental/check-docs.sh`	Updated `check_local_ref` to first consult Fern route existence and site-source checks for absolute site-route targets, retain existing broken-site-route error output, and adjusted phase-1 logging and success messages to mention Fern routes.
Test infrastructure and validation for Fern route links `test/check-docs-links.test.ts`	Introduced `REPO_ROOT` and an env-override for spawned `check-docs.sh`, extended a fixture MDX with an OpenClaw hardening href, and added Vitest cases that assert successful link rewriting across pages and expected failures for broken routes and an invalid Fern nav index.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested labels

documentation

Poem

🐰 I hop through index.yml and trails of links,
I map each Fern route with nimble kinks,
Hardening hrefs and tests take flight,
I check each path from morning to night,
Docs are tidy now — a rabbit's delight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding Fern route resolution to the docs link checker, which is the core objective of the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/docs-fern-link-checker

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-06-02T23:40:43Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: docs-validation-e2e

Dispatch hint: docs-validation-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No merge-blocking runtime E2E is recommended because the PR only changes docs validation tooling and its tests. Existing PR checks for docs links / CLI parity are the primary coverage; no sandbox, credential, inference, deployment, network policy, or real assistant user-flow behavior is affected.

Optional E2E

docs-validation-e2e (low): Optional confidence check for the modified check-docs.sh path. It runs CLI/docs parity plus markdown link validation through test/e2e/test-docs-validation.sh, including the changed link-checker logic.

New E2E recommendations

None.

Dispatch hint

Workflow: .github/workflows/nightly-e2e.yaml
jobs input: docs-validation-e2e

github-actions · 2026-06-02T23:40:44Z

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

None. Changed files are a docs-link unit test and a legacy/non-scenario E2E docs-check script outside test/e2e-scenario/ and scenario workflows; they do not affect scenario E2E behavior.

Optional scenario E2E

None.

Relevant changed files

None.

github-actions · 2026-06-02T23:42:22Z

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 3 prior items resolved, 0 still apply, 0 new items found

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/e2e/e2e-cloud-experimental/check-docs.sh`:
- Around line 837-851: The alias logic currently only handles wildcard paths and
misses bare variant roots and their user-guide equivalents; update the candidate
generation (using the candidates array and the route variable in the case/if
block) to also map bare "openclaw" and "hermes" to their variant home (append
"user-guide/openclaw/home" and "user-guide/hermes/home"), and likewise map
"user-guide/openclaw" and "user-guide/hermes" to "user-guide/<variant>/home" so
routes contributed by docs/index.yml (which use ".../home") are recognized.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d7604b0b-1be5-4507-a131-37adbdca4c0c

📥 Commits

Reviewing files that changed from the base of the PR and between f17a19a and 8642907.

📒 Files selected for processing (2)

test/check-docs-links.test.ts
test/e2e/e2e-cloud-experimental/check-docs.sh

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv · 2026-06-03T00:05:22Z

Addressed feedback in 3bd5a5a:

Added bare variant root aliases so /openclaw, /hermes, /user-guide/openclaw, and /user-guide/hermes resolve to the Fern home routes.
Made Fern route-index construction fail loudly instead of silently falling back when docs/index.yml cannot be parsed into routes.
Added regressions for invalid Fern routes and route-index parse/build failures.

Validation rerun:

npx prek run --all-files
bash -n test/e2e/e2e-cloud-experimental/check-docs.sh
npx vitest run test/check-docs-links.test.ts
CHECK_DOC_LINKS_REMOTE=0 bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-links --local-only

fix(docs): resolve Fern routes in link checker

8642907

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv self-assigned this Jun 2, 2026

coderabbitai Bot reviewed Jun 2, 2026

View reviewed changes

Comment thread test/e2e/e2e-cloud-experimental/check-docs.sh

cv added the v0.0.57 Release target label Jun 2, 2026

test(docs): cover Fern route edge cases

3bd5a5a

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv requested a review from miyoungc June 3, 2026 00:25

cv merged commit f90000b into main Jun 3, 2026
32 checks passed

cv deleted the fix/docs-fern-link-checker branch June 3, 2026 00:26

This was referenced Jun 3, 2026

docs: expand generated agent variants #4728

Merged

chore(skills): improve the user skill generation flow for NVSkills #4744

Merged

Conversation

cv commented Jun 2, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Scenario Advisor Recommendation

E2E Scenario Advisor

Required scenario E2E

Optional scenario E2E

Relevant changed files

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cv commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cv commented Jun 2, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading