--- 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 `//...` 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//.mdx`: ```mdx --- title: "" description: "One-line SEO description (or empty string)" position: 3 --- # ``` 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 "" 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`: ```mdx --- title: "Collect Rollouts" description: "Run the agent against your dataset and write results to JSONL" position: 4 --- # Collect Rollouts ``` 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`: ```yaml 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 | `...` | | Helpful tip | `...` | | Informational callout | `...` | | Warning | `...` | | Error / danger | `...` | | Card grid on index pages | `` with `` children | | Status/scope tag inside a Card | `tag` (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 `` grid. Each `` can carry one or more `` tags to indicate scope, status, or read-time. Valid intents: `success`, `note`, `tip`, `warning`, `error`, `info`, `launch`, `check`. Use `...` (no intent) for neutral tags. Place badges as the last line inside the ``, 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. ```mdx Install, start servers, and collect your first rollouts in one page. start here 5 min ``` ## Frontmatter Fields ```yaml --- title: "" # required — used for nav and

description: "" # required (may be empty string) — SEO position: 1 # optional — orders auto-discovered pages within a folder --- ``` The MDX body should still open with `# ` 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): ```bash 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`): ```bash 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/`): ```bash npm run generate:library # `fern docs md generate` ``` ## Commit & Preview ```bash git add fern/ git commit -s -m "docs: " ``` 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..`. Do not push a tag unless the user asks. ```bash 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 `
` | | 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/` and `//` show different content | They shouldn't — `latest.yml` should mirror the current GA version's yml and point at the same `.//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//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|dev|generate|generate:library` — each wraps `npx -y fern-api@latest` | | `.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 | ---