You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1986d70
Browse filesBrowse the repository at this point in the historyBrowse files
**`main/pages/` is the bleeding-edge tree** — every PR lands here and publishes under the `main` slug (`availability: beta`, shown as `Main · preview` in the picker). **`v26.04/pages/` is the current GA snapshot**; it changes only via deliberate back-port from `main`. `v26.02/`and `v25.09/`are older frozen GAs. `latest.yml` is a symlink to the current GA's nav (today: `v26.04.yml`), so `/latest/...` URLs serve the current train. At the next GA cut, snapshot `main/` to a new `vXX.YY/` and retarget the symlink.
90
+
**`main/pages/` is the bleeding-edge tree** — every PR lands here and publishes under the `main` slug (`availability: beta`, shown as `Main · preview` in the picker). **`v26.09/pages/` is the current docs-train snapshot**, cut from `main/pages/`; `main/`remains the preview source for ongoing work. Earlier version trees are preserved as historical documentation. `latest.yml` is a symlink to the current docs train's nav (today: `v26.09.yml`), so `/latest/...` URLs serve the current train. At the next cut, snapshot `main/` to a new `vXX.YY/` and retarget the symlink.
85
91
86
-
`display-name` in `docs.yml` pairs the **NeMo calendar train** (e.g. `26.04`) with the**git release tag** (e.g. `v1.1.2`) so the version picker matches PyPI/GitHub. Align these with `CHANGELOG.md` and `nemo_curator/package_info.py` when you ship. The `main` entry stays unpinned (`Main · preview`) because it tracks unreleased work.
92
+
`display-name` in `docs.yml` pairs the **NeMo calendar docs train** (e.g. `26.09`) with its**planned release tag** (e.g. `v1.4.0`) so the version picker reflects the release mapping. Check the release notes and GitHub release information before cutting a train; a docs cut does not itself publish a package release. The `main` entry stays unpinned (`Main · preview`) because it tracks unreleased work.
87
93
88
94
## Local development
89
95
@@ -112,7 +118,9 @@ The script temporarily injects a path-input `nemo-curator-local` entry into `doc
112
118
CI runs `substitute_variables.py` before `fern generate` so `{{ container_version }}` and other tokens in MDX are replaced. To run locally (from repo root):
Cross-version links (e.g. from a `v26.04/` page to a `v26.02/` page) trigger broken-link warnings in `fern docs dev`; those are **false positives** — Fern's local validator does not resolve cross-version slugs from `docs.yml`. The published site renders them correctly.
165
+
Cross-version links (e.g. from a `v26.09/` page to a `v26.07/` page) trigger broken-link warnings in `fern docs dev`; those are **false positives** — Fern's local validator does not resolve cross-version slugs from `docs.yml`. The published site renders them correctly.
When the next docs train is cut (replace `XX.YY` and `vX.Y.Z` with the values confirmed for that release):
179
190
180
-
1.`cp -r versions/v26.04 versions/v26.10` — fresh frozen snapshot of the bleeding-edge tree
181
-
2.`cp versions/v26.04.yml versions/v26.10.yml`, then rewrite `./v26.04/` path prefixes to `./v26.10/`
182
-
3. Retarget the GA alias symlink: `cd versions && ln -sfn v26.10.yml latest.yml`
183
-
4. Add the new entry to `docs.yml``versions:` (`display-name: "Latest · v1.2.0 (26.10)"`, etc.); demote/remove the oldest GA per the support policy
184
-
5. Add `redirects:` for legacy `/26.10` and `/26.10/:path*/index.html` patterns in `docs.yml`
185
-
6.`versions/v26.04/pages/` either keeps moving forward as the new bleeding-edge tree, or you start a new `v26.10/pages/` and freeze `v26.04/`
191
+
1. Copy `versions/main/pages/` to `versions/vXX.YY/pages/` to snapshot the current preview source. Preserve page bytes and placeholders.
192
+
2. Copy `versions/main.yml` to `versions/vXX.YY.yml`, then rewrite only `./main/` path prefixes to `./vXX.YY/`.
193
+
3. Retarget the latest alias symlink: `cd versions && ln -sfn vXX.YY.yml latest.yml`.
194
+
4. Add the new stable train to `docs.yml``versions:` and update the Latest display name to `Latest · vX.Y.Z (XX.YY)`. Keep `Main · preview` and retained historical trains.
195
+
5. Add the calendar-path, `index.html`, and `.html` redirects for `/XX.YY` in `docs.yml` before the generic catch-all redirects.
196
+
6. Mirror only existing secret-baseline findings for the copied pages, preserving each finding's type, hash, verification state, and line number.
197
+
7. Verify the snapshot matches `main/pages/`, the nav differs only in its version path prefix, and older version trees remain unchanged.
186
198
187
199
## CI and publishing
188
200
@@ -198,7 +210,7 @@ PRs that touch `fern/**` get a preview after their current head is approved and
198
210
199
211
Preview navigation, components, organization and tooling come from `main`; PRs supply only documentation content and assets. Existing unchanged trusted symlinks (such as `versions/latest.yml`) are allowed; new or retargeted PR symlinks are rejected. Explicit page/asset deletions relative to the PR merge base are applied, while pages added only on newer `main` remain available. Navigation changes are not previewed until they land on `main`; deleting a still-referenced page can therefore fail the build rather than silently showing its old content.
200
212
201
-
Fern CLI **5.123.0** is pinned in workflow code with `FERN_NO_VERSION_REDIRECTION=true`. Preview token access is limited to library generation and publication. The comment URL must match the exact expected Fern preview host; no authenticated page-link request is made. Reverting all docs changes removes existing bot preview comments without publishing or accessing the Fern token.
213
+
Fern CLI **5.149.0** is pinned in workflow code with `FERN_NO_VERSION_REDIRECTION=true`. Preview token access is limited to library generation and publication. The comment URL must match the exact expected Fern preview host; no authenticated page-link request is made. Reverting all docs changes removes existing bot preview comments without publishing or accessing the Fern token.
| Broken-link warning for cross-version path | False positive in `fern docs dev`; the published site resolves it correctly |
232
244
|`JSX expressions must have one parent element`| Wrap multi-element MDX content in `<>...</>` or a `<div>`|
233
245
| Old `/index.html` or `/foo.html` URL breaks | Add a `redirects:` entry in `docs.yml` (catch-alls for `:path*/index.html` and `:path*.html` already exist) |
234
-
|`{{ variable }}` shows literally on the published page | Run `python fern/substitute_variables.py versions/v26.04 --version 26.04` before `fern generate`, or check the variable is registered in `DEFAULT_VARIABLES`|
246
+
|`{{ variable }}` shows literally on the published page | Run `python fern/substitute_variables.py versions/vXX.YY --version XX.YY` before `fern generate`, or check the variable is registered in `DEFAULT_VARIABLES`|
235
247
| Library reference missing or stale | Check `libraries:` block in `docs.yml` matches the package source path; see [`./AUTODOCS_GUIDE.md`](./AUTODOCS_GUIDE.md)|
0 commit comments