docs: keep page URLs aligned with file paths by johnnygreco · Pull Request #3713 · NVIDIA/OpenShell

johnnygreco · 2026-09-25T16:02:39Z

Summary

Align published docs URLs, file paths, and sidebar labels, restore the Tutorials landing page, and add a navigation check to prevent these inconsistencies from recurring.

Related Issue

No issue required: localized docs navigation fixes and regression checks.

Changes

Rename the first-agent, GitHub push-access, and image-verification files to match their existing URLs.
Align the About overview and TypeScript SDK URLs with their file paths, preserving the published /about/why-open-shell and /sdk/type-script URLs through redirects for dev, latest, and unversioned links to latest.
Align sidebar labels and expose tutorials/index.mdx as the Tutorials section page. Preserve the current Pi with OpenRouter navigation.
Fix four existing agent-guide redirects for dev and latest.
Add docs:nav and 12 regression tests to detect URL/file mismatches, sidebar-label mismatches, orphaned pages, and invalid redirects for the checked version. Run them through the docs and test tasks and docs preview workflow.
Document the navigation rules in contributor guidance, the docs-update skill, and the build architecture overview.

The redirect synchronization merged in #3754 installs each channel's aliases with its updated pages; publishing dev leaves latest redirects unchanged.

Testing

Validation:

mise run pre-commit passes
mise run docs passes (Fern: zero errors, three warnings; navigation check passes)
mise run test:docs-nav passes: 12 tests
mise run test:docs-website passes: 26 tests
npx --yes fern-api@5.112.0 docs broken-links passes
Local replay against the production docs snapshot: a dev sync installs its two aliases and leaves latest unchanged; a subsequent latest sync installs its aliases alongside the renamed pages. The two unversioned aliases are also owned by latest and stay unchanged during a dev sync.
E2E tests added/updated (not applicable to docs navigation)

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture docs updated

copy-pr-bot · 2026-09-25T16:02:43Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

github-actions · 2026-09-25T16:03:09Z

🌿 Preview your docs: https://nvidia-preview-pr-3713.docs.buildwithfern.com/openshell

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

johnnygreco · 2026-09-28T00:13:33Z

/ok to test 6ceeaa8

purp

gator-agent

PR Review Status

This localized documentation-navigation change is valid for OpenShell, and the initial code-only review found no blocking issues. The new navigation validator, regression tests, workflow wiring, and contributor guidance cover the changed behavior; all required checks on the current head are green.

Action required: A maintainer must review and approve the PR.

Blocking findings:

No blocking findings remain

Carried findings:

None

Non-blocking suggestions:

None

Gator metadata

Validation: Maintainer-authored, concentrated documentation navigation and validation work with a clear user-facing goal and test path
Docs: Fern docs and navigation are the subject of this change and are updated together
Checks: Required current-head checks are green
E2E: N/A; no sandbox, runtime, policy, provider, driver, or packaging behavior changes
Head SHA: 6ceeaa8ab5b9c3bb993706960ad544481ae80b59
Base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Merge base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Patch ID: 53938436f7abe2509065ce633f5b35c5783b4b3f
Gator payload: 9
Review mode: initial
Previous reviewed SHA: none
Review budget exhausted: no
Maintainer decision required: no
Next state: gator:approval-needed

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

johnnygreco · 2026-09-28T01:42:31Z

/ok to test 00aa5ee

purp

gator-agent

PR Review Status

Thanks @johnnygreco. I checked your latest update restoring the published Overview and TypeScript aliases for both dev and latest; the focused follow-up review found no blocking issues, and all required checks on this head are green.

Action required: A maintainer must review and approve the PR.

Blocking findings:

No blocking findings remain

Carried findings:

None

Gator metadata

Validation: Maintainer-authored, concentrated documentation navigation and validation work with a clear user-facing goal and test path
Docs: Fern redirects preserve the renamed published URLs, and navigation is updated with the docs changes
Checks: Required current-head checks are green
E2E: N/A; no sandbox, runtime, policy, provider, driver, or packaging behavior changes
Head SHA: 00aa5eeabd62190b86f8a426a86b8376245737dd
Base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Merge base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Patch ID: e3a5b842b426df0925d81b9c43bbbba1e784c942
Gator payload: 9
Review mode: follow_up
Previous reviewed SHA: 6ceeaa8ab5b9c3bb993706960ad544481ae80b59
Review budget exhausted: no
Maintainer decision required: no
Next state: gator:approval-needed

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

purp

LGTM 🚢

johnnygreco · 2026-09-28T02:00:37Z

/ok to test 6bc38ba

purp

gator-agent

PR Review Status

Thanks @johnnygreco. I checked the latest update that adds the unversioned Overview and TypeScript redirects to latest; the focused follow-up review found no blocking issues. Required checks are green and maintainer approval is present, so this PR is ready for a maintainer merge or close decision.

Blocking findings:

No blocking findings remain

Carried findings:

None

Gator metadata

Validation: Maintainer-authored, concentrated documentation navigation and validation work with a clear user-facing goal and test path
Docs: Fern redirects preserve the renamed published URLs for unversioned, dev, and latest paths, and navigation is updated with the docs changes
Checks: Required current-head Branch Checks and Helm Lint are green; DCO and Trivy Changes also passed
E2E: N/A; no sandbox, runtime, policy, provider, driver, or packaging behavior changes
Head SHA: 6bc38ba99f0fe900f994a07703ec8d76457663b3
Base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Merge base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
Patch ID: 72654124e63e41b21bfaf02793d8381ea9556eeb
Gator payload: 9
Review mode: follow_up
Previous reviewed SHA: 00aa5eeabd62190b86f8a426a86b8376245737dd
Review budget exhausted: no
Maintainer decision required: no
Next state: gator:merge-ready

johnnygreco requested review from a team, derekwaynecarr, mrunalp and sjenning as code owners September 25, 2026 16:02

johnnygreco mentioned this pull request Sep 25, 2026

docs(policy): refresh policy documentation and references #3563

Merged

6 tasks

johnnygreco requested a review from pimlock September 25, 2026 17:56

pimlock reviewed Sep 25, 2026

View reviewed changes

Comment thread fern/docs.yml Outdated

This was referenced Sep 25, 2026

docs(tutorials): run Pi with OpenRouter #3722

Merged

fix(docs): sync redirects with versioned snapshots #3754

Merged

johnnygreco added 4 commits September 28, 2026 00:04

docs: align page file names and nav labels with published URLs

31789f6

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

docs: redirect moved dev pages and fix agent guide redirects

1de161d

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

ci(docs): check that page URLs match their file paths

7fb0c81

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

fix(docs): align navigation checks with repo conventions

149bfef

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

johnnygreco force-pushed the docs-nav-path-consistency/jg branch from 1c52618 to 149bfef Compare September 28, 2026 00:07

docs: omit historical redirect aliases

6ceeaa8

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

johnnygreco requested a review from pimlock September 28, 2026 00:13

purp reviewed Sep 28, 2026

View reviewed changes

purp added the gator:approval-needed Gator completed review; maintainer approval needed label Sep 28, 2026

fix(docs): preserve published overview and TypeScript URLs

00aa5ee

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

purp reviewed Sep 28, 2026

View reviewed changes

fix(docs): redirect unversioned overview and TypeScript URLs

6bc38ba

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

purp approved these changes Sep 28, 2026

View reviewed changes

purp enabled auto-merge September 28, 2026 01:57

purp added this pull request to the merge queue Sep 28, 2026

purp reviewed Sep 28, 2026

View reviewed changes

purp added gator:merge-ready and removed gator:approval-needed Gator completed review; maintainer approval needed labels Sep 28, 2026

Merged via the queue into main with commit 87929ad Sep 28, 2026
75 of 76 checks passed

purp deleted the docs-nav-path-consistency/jg branch September 28, 2026 02:19

drew added this to the OpenShell 0.1.2 milestone Sep 28, 2026

Navigation Menu

docs: keep page URLs aligned with file paths - #3713

docs: keep page URLs aligned with file paths#3713
purp merged 7 commits into
mainfrom
docs-nav-path-consistency/jg

johnnygreco commented Sep 25, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Sep 25, 2026

Uh oh!

github-actions Bot commented Sep 25, 2026

Uh oh!

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Uh oh!

purp left a comment

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

johnnygreco commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

copy-pr-bot Bot commented Sep 25, 2026

Uh oh!

github-actions Bot commented Sep 25, 2026

Uh oh!

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

purp left a comment

Choose a reason for hiding this comment

Uh oh!

johnnygreco commented Sep 28, 2026

Uh oh!

purp left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

johnnygreco commented Sep 25, 2026 •

edited

Loading