docs(fern): fix redirects so Sphinx URLs actually resolve - #1310
Merged
Conversation
With `experimental.basepath-aware: true`, Fern requires the full `/nemo/gym/` basepath with a leading slash on both source and destination of every redirect rule. The previous block had two systematic issues: legacy Sphinx sources omitted the leading slash (`nemo/gym/foo.html`), and most destinations omitted the basepath (`/latest/foo`). Result: every old-style URL from the README returned 404 with no redirect. Mirror the working pattern from nemo-curator's docs.yml and add three explicit redirects for pages renamed during the Fern migration (`unsloth-training`, `apidocs`, `creating-training-environment`). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Lawrence Lane <llane@nvidia.com>
Fern's `:path*` placeholder does not match the empty-path case, so the catch-all `/nemo/gym/<version>/:path*/index.html` rule failed for `/nemo/gym/latest/index.html` — Fern emitted a literal `:path*` in the Location header instead of substituting. Curator hit the same issue and solved it with explicit per-version rules; mirror that here for `latest`, `v0.2.1`, and `main`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Lawrence Lane <llane@nvidia.com>
# Conflicts: # fern/docs.yml
3 tasks
cmunley1
approved these changes
May 14, 2026
9 tasks
lbliii
added a commit
that referenced
this pull request
May 15, 2026
… drop Main beta, fix duplicate H1 (#1328) ## Summary Bundled Fern docs fixes on one branch. ### 1. Scope `detailed-setup` / `rollout-collection` redirects to `main` - PR #1310 added two redirect rules sourced at `/nemo/gym/latest/get-started/{detailed-setup,rollout-collection}` → `/quickstart`. But the `latest` Fern slug was sourced from `v0.2.1` (the current GA), and both pages still exist there — so the redirects were 308-ing live GA pages away. - The consolidation into `quickstart` only happened on the `main` source content. Flip the redirect source prefix from `/latest/` to `/main/`. ### 2. Remove duplicate H1 on `main` home landing page - Fern auto-renders the frontmatter `title` as the page's H1. `fern/versions/latest/pages/about/index.mdx` (the `main` home landing per #1320) also had an explicit `# NeMo Gym` heading in the body, producing two stacked H1s. - Remove the body heading; let the frontmatter title stand alone. ### 3. Retire the `Latest` version slug; alias `/latest/*` → `/main/*` - The `Latest` dropdown entry pointed at v0.2.1 content, making slug semantics backwards from user expectation ("latest" should mean "newest", not "last GA"). - Remove `Latest` from the `versions:` block. - Add catch-all redirects so any inbound `/nemo/gym/latest/...` URL lands on the equivalent `/main/...` path, mirroring the existing `/v0.2` → `/v0.2.1` alias pattern. - Dropdown after this change: `Main` (trunk, default) and `0.2.1` (pinned historical GA). ### 4. Drop the `beta` badge from `Main` - With `Latest` retired, `Main` is the canonical version users see. PM intent is "latest = main", treated as stable; drop the `availability: beta` flag. `0.2.1` keeps its `stable` badge. ### 5. Flatten `/latest/` redirect destinations to `/main/` - Existing page-reorg and Sphinx `index.html` rules still had destinations under `/nemo/gym/latest/...`. With `/latest/` reachable only via the new catch-all, those rules chained through a second hop. - Rewrite each destination directly to the `/main/...` equivalent so redirects resolve in one hop. Each target verified to exist in main's source content (`fern/versions/latest/pages/`). ## Test plan - [x] Confirmed `fern/versions/v0.2.1/pages/get-started/detailed-setup.mdx` and `rollout-collection.mdx` exist (current GA content under `0.2.1`). - [x] Confirmed `fern/versions/latest/pages/get-started/` (the `main` slug's source) only contains `installation`, `prerequisites`, `quickstart`. - [x] Confirmed frontmatter `title: "NeMo Gym"` is intact on the home landing. - [x] Verified each `/main/...` flatten target exists in `fern/versions/latest/pages/` before rewriting destinations. - [x] Verified on `nvidia-gym.docs.buildwithfern.com` after publish: `/latest/get-started/detailed-setup` → 200, `/main/get-started/detailed-setup` → 308 → quickstart (same for rollout-collection). - [ ] Post-merge + republish: dropdown shows only `Main` (no badge) and `0.2.1` (stable). - [ ] Post-merge + republish: `curl -sI https://nvidia-gym.docs.buildwithfern.com/nemo/gym/latest/about` returns 308 → `/main/about` (single hop). - [ ] Post-merge + republish: `curl -sI https://nvidia-gym.docs.buildwithfern.com/nemo/gym/latest/about/concepts/core-components` returns 308 → `/main/about/core-components` (single hop, flattened). - [ ] Post-merge + republish: `https://nvidia-gym.docs.buildwithfern.com/nemo/gym/main` renders exactly one "NeMo Gym" H1. ## Known caveat There is an outstanding Fern issue where redirects work on the buildwithfern preview hostname but don't propagate to the `docs.nvidia.com` custom-domain hostname (etag differs between the two, both hit Vercel). That's a separate problem — not this PR's concern. The Akamai-layer root redirect on `docs.nvidia.com` currently sends `/nemo/gym/` to `/nemo/gym/latest/index.html`; once Fern's `/latest/index.html` → `/main` rule is live, those hops will land on `/main/` in one step. --------- Signed-off-by: Lawrence Lane <llane@nvidia.com>
lbliii
added a commit
that referenced
this pull request
May 22, 2026
## Summary - Replace legacy Sphinx-style `.html` URLs in the root `README.md` with canonical Fern URLs, so links resolve directly without relying on a redirect layer (#1310 is in flight to fix that layer separately; this PR sidesteps it for the high-traffic README). - All 13 target URLs verified `200` against the Fern preview hostname. Notable mappings: - `latest/index.html` → `latest/documentation/home` - `latest/apidocs/index.html` → `latest/api/reference/api-reference` - `*/index.html` → `*` (section indexes — `agent-server`, `training-tutorials`, `environment-tutorials`, `contribute`, etc.) - `unsloth-training.html` → `unsloth` (page was renamed during Fern migration) - `verl.html` and `get-started/prerequisites` have no canonical page in `latest`, so they now point at the section index (`training-tutorials`, `get-started`) ## Test plan - [x] Diff the README — all `docs.nvidia.com/nemo/gym/.../*.html` URLs eliminated. - [x] `curl -sI` every updated URL against `nvidia-gym.docs.buildwithfern.com` — 13/13 returned `200`. - [ ] Post-merge: spot-check the rendered README on GitHub and confirm each link opens the expected page. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Lawrence Lane <llane@nvidia.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs.nvidia.com/nemo/gym/*.htmllinks fromREADME.mdwere returning 404 with no redirect on the production Fern preview (https://nvidia-gym.docs.buildwithfern.com/).experimental.basepath-aware: true, Fern requires the full/nemo/gym/basepath with a leading slash on both source and destination of every redirect rule (verified by comparing to nemo-curator's workingdocs.yml). Our block had two systematic issues:nemo/gym/foo.html) → never matched./latest/foo) → matched but emitted aLocationoutside the basepath, still 404.unsloth-training→unsloth,apidocs→api/reference/api-reference,creating-training-environment→single-step-environment.Test plan
training-tutorials/verlis a stale-deploy issue, separate from redirects.)curl -sI <old-url>against each old Sphinx URL; expect308+ aLocation:header pointing at the canonical Fern path.🤖 Generated with Claude Code