nemo-gym-docs

name	nemo-gym-docs
description	Maintain the NeMo Gym Fern docs site — add, update, move, or remove pages under fern/. Use for any documentation change. Triggered by: "edit docs", "add doc page", "update docs", "rename page", "fix broken link", "add redirect", "preview docs", "publish docs", any request that touches `fern/`.

NeMo Gym Docs Maintenance

Unified skill for adding, updating, moving, and removing pages on the NeMo Gym Fern documentation site.

Scope Rule

ALL docs edits happen under fern/. All new pages — including release notes and migration guides — belong under fern/.

Bleeding-edge tree + GA snapshots. Gym keeps one bleeding-edge content tree at fern/versions/latest/ (the folder name is historical — it's mounted under the main slug via main.yml) and one frozen GA snapshot per shipped release (currently fern/versions/v0.2.1/). All new edits land in fern/versions/latest/. The latest.yml file is a GA alias — a symlink to the current GA's yml — so /latest/... and /<current-ga>/... serve the same pages. Back-ports into a frozen GA snapshot are deliberate and rare; default to editing fern/versions/latest/ only.

Layout at a Glance

fern/
├── fern.config.json          # Org + Fern CLI version (currently 4.80.3)
├── package.json              # `npm run dev|check|generate` — wraps `npx -y fern-api@latest`
├── docs.yml                  # Site config: instances, versions, tabs, redirects, libraries
├── versions/
│   ├── latest.yml            # GA alias — symlink to the current GA's yml (currently v0.2.1.yml)
│   ├── main.yml              # Nav tree for the bleeding-edge train (mounts ./latest/pages)
│   ├── latest/pages/         # MDX content for the bleeding-edge train (slug: main)
│   ├── v0.2.1.yml            # Nav tree for the 0.2.1 GA snapshot
│   └── v0.2.1/pages/         # MDX content for the 0.2.1 GA snapshot
├── components/               # Custom TSX (CTAButtons, NavButton, CustomFooter)
├── assets/                   # Images, SVGs, favicon
├── main.css                  # Global theme overrides (NVIDIA green, badge spacing, etc.)
└── product-docs/             # GENERATED library reference (gitignored)

File system                                            Published URL
─────────────────────────────────────────────────────  ──────────────────────────────────
fern/versions/latest/pages/get-started/quickstart.mdx  docs.nvidia.com/nemo/gym/main/get-started/quickstart
fern/versions/v0.2.1/pages/get-started/quickstart.mdx  docs.nvidia.com/nemo/gym/v0.2.1/get-started/quickstart
                                                       docs.nvidia.com/nemo/gym/latest/get-started/quickstart  (GA alias)

Operations

Add a Page

1. Gather: page title, target section, filename (kebab-case .mdx), subdirectory under fern/versions/latest/pages/.

2. Create fern/versions/latest/pages/<subdirectory>/<filename>.mdx:

   ---
   title: "<Page Title>"
   description: "One-line SEO description (or empty string)"
   position: 3
   ---
   
   # <Page Title>
   
   <content>
   

3. If the parent folder is mounted in main.yml with title-source: frontmatter, the page is auto-discovered — no nav edit needed. Otherwise add a - page: entry under the right section: in fern/versions/main.yml.

4. Do not mirror into the current GA snapshot folder (e.g., v0.2.1/) — frozen GA snapshots only get back-ports on explicit request.

Update a Page

1. Locate by path, title, or keyword (grep -rn in fern/versions/latest/pages/).
2. Content only — edit the MDX in fern/versions/latest/pages/. Don't touch v0.2.1/ unless this is an explicit back-port.
3. Title change — update the frontmatter title: and (if the parent uses title-source: frontmatter) nothing else; otherwise update the nav - page: entry too.
4. Section move — git mv the file, update its path: in main.yml, fix all incoming links inside fern/versions/latest/pages/.
5. Slug change — folders use the page filename for the slug. Renaming the file changes the URL; add a redirect in fern/docs.yml so the old URL keeps working.

Remove a Page

1. Find incoming links: grep -rn "<filename>" fern/versions/latest/pages --include="*.mdx".
2. git rm the file from fern/versions/latest/pages/.
3. Remove the matching - page: block from main.yml if it was a manual entry.
4. Fix or remove all incoming links.
5. Add a redirect in fern/docs.yml if the URL was public.

Back-port to a GA Snapshot

Only back-port when the user explicitly asks ("back-port to v0.2.1"). Apply the same change inside the GA snapshot's pages/ folder (e.g., fern/versions/v0.2.1/pages/) and update its yml if needed. latest.yml is a symlink to the current GA's yml, so nav changes propagate automatically.

Worked Example: Adding a Page

Request: "Add a how-to for collecting rollouts under Get Started."

1. Create fern/versions/latest/pages/get-started/rollout-collection.mdx:

   ---
   title: "Collect Rollouts"
   description: "Run the agent against your dataset and write results to JSONL"
   position: 4
   ---
   
   # Collect Rollouts
   
   <content>
   

2. The get-started folder in main.yml uses title-source: frontmatter, so the page appears automatically. position: 4 controls ordering — it's optional; without it, pages sort alphabetically by filename.

3. cd fern && npm run check && npm run dev, verify /main/get-started/rollout-collection renders.

Worked Example: Renaming a Slug (with Redirect)

Request: "Rename /main/get-started/setup to /main/get-started/detailed-setup."

1. git mv fern/versions/latest/pages/get-started/setup.mdx fern/versions/latest/pages/get-started/detailed-setup.mdx.

2. Add a redirect in fern/docs.yml:

   redirects:
     - source: "/main/get-started/setup"
       destination: "/main/get-started/detailed-setup"
   

3. grep -rn "/get-started/setup" fern/versions/latest/ and update any incoming links.

---

Content Guidelines

NeMo Gym uses Fern-native MDX components directly. Do not use GitHub > [!NOTE] syntax — it will not render.

Purpose	Component
Neutral aside	<Note>...</Note>
Helpful tip	<Tip>...</Tip>
Informational callout	<Info>...</Info>
Warning	<Warning>...</Warning>
Error / danger	<Error>...</Error>
Card grid on index pages	<Cards> with <Card title="..." href="..."> children
Status/scope tag inside a Card	<Badge minimal outlined>tag</Badge> (see below)

Images live in fern/assets/ (shared) or under a version's pages/ (version-scoped). Reference with root-relative paths.

Cards and Badges

Index pages use a <Cards> grid. Each <Card> can carry one or more <Badge> tags to indicate scope, status, or read-time.

Valid intents: success, note, tip, warning, error, info, launch, check. Use <Badge minimal outlined>...</Badge> (no intent) for neutral tags.

Place badges as the last line inside the <Card>, separated by a blank line from the body text. The CSS in main.css (.fern-card .fern-docs-badge) handles spacing — do not add inline style= props.

<Cards>
  <Card title="Quickstart" href="/main/get-started/quickstart">
    Install, start servers, and collect your first rollouts in one page.

    <Badge intent="success" minimal outlined>start here</Badge> <Badge minimal outlined>5 min</Badge>
  </Card>
</Cards>

Frontmatter Fields

---
title: "<Page Title>"        # required — used for nav and <h1>
description: ""              # required (may be empty string) — SEO
position: 1                  # optional — orders auto-discovered pages within a folder
---

The MDX body should still open with # <Page Title> matching the frontmatter title. Folders using title-source: frontmatter in the version YAML pull the nav label from title:.

Validate

First-time setup: authenticate the CLI against the nvidia Fern org via Google SSO (one-time, browser flow):

npx -y fern-api@latest login    # opens browser → sign in with your @nvidia.com Google account

Run from fern/ (no install step — scripts shell out to npx -y fern-api@latest):

npm run check       # `fern check` — YAML + frontmatter validation
npm run dev         # `fern docs dev` — localhost:3000 hot-reload preview

fern check must pass before commit. The dev server's broken-link warnings for cross-version links like /latest/about are false positives — Fern's local validator does not resolve the version slug from docs.yml against latest.yml. The published site renders them correctly.

To regenerate the autodoc library reference (gitignored under product-docs/):

npm run generate:library    # `fern docs md generate`

Commit & Preview

git add fern/
git commit -s -m "docs: <add|update|remove> <page-title>"

PRs that touch fern/** get an automatic Fern preview URL posted as a comment by .github/workflows/fern-docs-preview-comment.yml. No manual step needed.

                    ┌─ fern-docs-ci.yml                  → fern check
PR (touches fern/) ─┼─ fern-docs-preview-build.yml       → upload fern/ artifact (no secrets)
                    └─ fern-docs-preview-comment.yml     → 🌿 preview URL comment

Push to main (touches docs/** or fern/**) → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Tag push (docs/v*)                        → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Manual dispatch                           → publish-fern-docs.yml → docs.nvidia.com/nemo/gym

The preview-comment + publish jobs require the DOCS_FERN_TOKEN repository or organization secret (from fern token).

Publishing to Production

Production publishes on three triggers (see .github/workflows/publish-fern-docs.yml):

1. Push to main when docs/** or fern/** changes — continuous staging.
2. Tag push matching docs/v* — versioned release.
3. Manual dispatch from the Actions tab.

Tag format must be docs/v<MAJOR>.<MINOR>.<PATCH>. Do not push a tag unless the user asks.

git tag docs/v0.3.0
git push origin docs/v0.3.0

URL → version mapping:

docs.nvidia.com/nemo/gym/latest/...   → GA alias (currently mirrors v0.2.1)
docs.nvidia.com/nemo/gym/main/...     → bleeding-edge train (folder: ./latest/pages)
docs.nvidia.com/nemo/gym/v0.2.1/...   → 0.2.1 GA snapshot

Cutting a New Version Train

When the user ships a new version (e.g. v0.3.0):

1. cp -r fern/versions/latest fern/versions/v0.3.0 — frozen snapshot of the bleeding-edge folder.
2. cp fern/versions/main.yml fern/versions/v0.3.0.yml and rewrite ./latest/ path prefixes to ./v0.3.0/.
3. Retarget the fern/versions/latest.yml symlink at the new GA's yml: cd fern/versions && ln -sfn v0.3.0.yml latest.yml.
4. In fern/docs.yml versions:, add the new GA snapshot entry (display-name: "0.3.0", slug: v0.3.0, availability: stable) and demote/remove the previous GA snapshot per the support policy.
5. fern/versions/latest/pages/ keeps moving forward as the bleeding-edge tree. main.yml is unchanged.
6. Tag docs/v0.3.0 and push to publish.

Debugging

Symptom	Fix
fern check YAML error	2-space indent; - page: inside contents:; path: is relative to the version YAML file
Page 404 in preview	slug: missing/duplicated in the same section; or position: collision in an auto-discovered folder
Broken-link warning for /latest/... cross-version link	False positive in fern docs dev; works on published site
JSX expressions must have one parent element	Wrap multi-element MDX content in <>...</> or a <div>
Old URL breaks (page renamed/moved)	Add a redirects: entry in fern/docs.yml
Library reference missing	npm run generate:library in fern/
Broken image	Path is relative to the MDX file; check fern/assets/ exists
Card badges have no spacing	Don't add inline styles — main.css .fern-card .fern-docs-badge rules handle it
/latest/<page> and /<current-ga>/<page> show different content	They shouldn't — latest.yml should mirror the current GA version's yml and point at the same ./<current-ga>/pages/... content. Sync them.

Key References

File	Purpose
fern/docs.yml	Site config, versions, redirects, libraries
fern/versions/latest.yml	GA alias — symlink to the current GA's yml
fern/versions/main.yml	Nav tree for the bleeding-edge train (mounts ./latest/pages)
fern/versions/v0.2.1.yml	Nav tree for the 0.2.1 GA snapshot
fern/versions/<ver>/pages/	MDX content for a version
fern/components/	Custom TSX (CTAButtons, NavButton, CustomFooter)
fern/assets/	Shared images, SVGs, favicon
fern/main.css	Global theme overrides — NVIDIA green, card/badge spacing
fern/package.json	`npm run check
.github/workflows/fern-docs-*.yml	CI: check, preview build, preview comment
.github/workflows/publish-fern-docs.yml	CI: publish to docs.nvidia.com/nemo/gym

---