docs: fern docs#26
Open
lbliii wants to merge 12 commits into
Open
Conversation
First step of the mkdocs → fern migration. Adds the fern config, components, styles, and scripts at docs/fern/ — no pages or content yet, those land in subsequent commits. Layout: - docs/fern/fern.config.json, package.json, docs.yml — fern build config - docs/fern/components/ — custom React components (Button, Icon, NotebookViewer, BadgeLinks, CustomFooter, MetricsTable, TrajectoryViewer, Authors) - docs/fern/styles/ — component CSS (notebook-viewer, button) - docs/fern/assets/ — shared SVGs/images (NVIDIA marks, agent eval framework diagram, etc.) - docs/fern/main.css — NVIDIA theme overrides - docs/fern/scripts/ — ipynb-to-fern-json converter, validate-mdx parse gate, substitutions.json - docs/fern/versions/latest.yml — nav scaffold (paths will be rewritten to ../../<page>.mdx in a later commit once pages exist at docs/<section>/<page>.mdx) Signed-off-by: Lawrence Lane <llane@nvidia.com>
Same-directory `.md → .mdx` rename for 194 files under docs/ (R100 in git's view — pure renames, no content change). Per-file blame and history follow through this commit unchanged. Also retires the mkdocs build: - mkdocs.yml: removed. - docs/Makefile: removed (mkdocs targets only). - docs/_hooks/, _overrides/, _scripts/, template/: mkdocs-specific infrastructure. - docs/_images/, docs/images/, docs/javascripts/, docs/stylesheets/: mkdocs theme assets (NVIDIA marks already mirrored under docs/fern/assets/). - docs/README.mdx, docs/CONTRIBUTING.mdx: mkdocs-build orientation; superseded by docs/fern/README.md. The next commit applies the MkDocs → MDX content rewrite (admonitions, tabs, autolinks, etc.) on top of these renames so the conversion diff is reviewable per file in isolation. Signed-off-by: Lawrence Lane <llane@nvidia.com>
Applies the MkDocs → Fern MDX conversion to every renamed .mdx page
under docs/ (in-place, on top of commit C2's renames). Reviewers can
see the per-file conversion diff with:
git show <C3-sha> -- docs/<file>.mdx
Conversion rules (implemented in .context/sync-fern/convert_docs_to_fern.py):
- Synthesize front matter from the H1 (when one isn't already present);
strip the matching H1 from the body.
- {{platform_name}} / {{ngm_short_name}} / etc. → resolved against
docs/fern/scripts/substitutions.json.
- !!! note/tip/warning/error/danger → <Note>/<Tip>/<Warning>/<Error>.
- ??? "Title" / ???+ collapsibles → <Accordion title="...">.
- === "Tab" + indented children → <Tabs><Tab title="..."> (handles
nested code fences that escape the tab's indent).
- <div class="grid cards" markdown> → <Cards><Card href title>.
- --8<-- "path.md" → import + <Component /> (snippets live under
docs/fern/snippets/, landed in commit C4); --8<-- "path.{json,jsonl,
sh,py,yml}" → inlined as a fenced code block at the include site.
- :material-foo: → <Icon name="..." /> + import.
- [Text](url){ .md-button } / .md-button--primary → <Button
href variant>; other attribute lists stripped.
- {width=200px} → strip the attribute list.
- HTML void tags <br>/<hr>/<img> → self-closing JSX (<br /> etc).
- <https://...> autolinks → [url](url).
- {% raw %} / {% endraw %} → removed (no-ops in Fern).
- <!-- HTML comments --> → removed (MDX rejects).
- Bare `<` and `{` in prose → escaped as `\<` / `\{`.
- `|` inside inline-code in a table row → escaped as `\|` (Fern's
MDX table preprocessor splits on `|` even inside code spans).
- Blank lines inserted around block-level JSX (Accordion, Note, Tabs,
Cards) so MDX treats children as markdown.
Also retargets docs/fern/scripts/validate-mdx.mjs at the new layout:
walks `..` (i.e. docs/) and skips docs/fern/ itself. All 194 pages
parse cleanly with @mdx-js/mdx 3.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
Move MkDocs-style snippet partials (the files referenced by --8<--
includes) under docs/fern/snippets/ so the @/snippets/* imports the
C3 converter emitted resolve via Fern's `@/` alias.
Pure partials (renamed, history preserved):
- docs/_snippets/* → docs/fern/snippets/_snippets/*
- docs/customizer/tutorials/_snippets/customizer-prereqs.mdx →
docs/fern/snippets/customizer/tutorials/_snippets/customizer-prereqs.mdx
- docs/data-designer/_snippets/{job-results,preview-results}.mdx →
docs/fern/snippets/data-designer/_snippets/*
Page-plus-snippet (kept at their canonical doc location AND copied
under snippets for include resolution):
- docs/evaluator/benchmarks/{discover-industry-benchmarks,hf-secret}.mdx
→ also at docs/fern/snippets/evaluator/benchmarks/ (without
front matter, since snippets render inline).
External include (out-of-tree pre-existing SDK README mirrored as a
partial):
- sdk/python/overrides/nemo-platform/README/03_usage.md →
docs/fern/snippets/sdk/python/overrides/nemo-platform/README/03_usage.mdx
The guardrails snippet *images* (car-audio-theft.jpg, street-scene.jpg)
stay at docs/guardrails/_snippets/input/ — they're referenced by
multimodal-data tutorial via a relative `../_snippets/input/` path
that already resolves.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
Adds Jupyter notebook rendering, reusing the pattern from
NVIDIA-NeMo/DataDesigner (script ipynb-to-fern-json.py landed in C1
under docs/fern/scripts/).
- docs/fern/components/notebooks/*.{json,ts}: 14 generated payloads
for the 6 customizer tutorials and 1 example-applications notebook.
The .ts file is a thin default-export wrapper around the .json
(Fern's bundler resolves .ts imports cleanly).
- docs/customizer/tutorials/{sft,lora,dpo,distillation,embedding,
optimize-throughput}-customization-job.mdx and
docs/example-applications/tool-calling.mdx: thin MDX wrapper pages
that import the notebook payload and render via <NotebookViewer>
with a colab badge.
Regenerate any notebook payload with:
python3 docs/fern/scripts/ipynb-to-fern-json.py \
docs/customizer/tutorials/sft-customization-job.ipynb \
-o docs/fern/components/notebooks/sft-customization-job.json
The .ipynb sources stay at their original paths so the converter has
a stable input and Colab badges link back to the canonical notebook.
Signed-off-by: Lawrence Lane <llane@nvidia.com>
Adds the Fern nav YAML so the converted pages actually show up in the sidebar. Every nav entry repoints from the legacy `./latest/pages/<x>.mdx` shape to `../../<x>.mdx`, matching the docs/<section>/<page> layout established in C2/C3. Also whitelists fern/versions/latest.yml in docs/.gitignore — the existing `*latest*` rule was meant to ignore mkdocs build artifacts and was hiding the fern nav file. Dropped one stale Studio > Optimizations entry whose underlying docs/studio/optimizations.mdx wasn't part of the squash on NVIDIA-NeMo/nemo-platform main yet. Validation: - `npx fern check`: 0 errors, 1 warning (pre-existing accent contrast). - `validate-mdx`: 193 MDX files parse cleanly. Signed-off-by: Lawrence Lane <llane@nvidia.com>
Use `global-theme: nvidia` from NVIDIA/fern-components for shared
colors, footer, logos, layout, and Adobe DTM JS. Keep only a partial
`logo: { right-text: NeMo Platform }` override and the functional
notebook-viewer/button CSS. Set `multi-source: true` on the instance
to match Curator's pattern. Repoint navbar GitHub link to the new
NVIDIA-NeMo/nemo-platform repo.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Signed-off-by: Lawrence Lane <llane@nvidia.com>
…pages
Pages mounted from outside docs/fern/ (via `path: ../../foo.mdx` in
versions/latest.yml) couldn't resolve `@/snippets/...` or
`@/components/...` imports — Fern's bundler refuses the `..`-escape
back into the fern dir, surfacing as `Could not resolve` errors at
build time.
Three swaps, all using Fern's documented patterns:
- Snippets: `import X from "@/snippets/foo.mdx"` + `<X />` →
`<Markdown src="/snippets/foo.mdx" />` (Fern-native JSX, bypasses
esbuild). 18 pages.
- Components: drop `import { Button } from "@/components/Button"` —
bare `<Button>` tags work via experimental.mdx-components. 3 pages.
- NotebookViewer: register all 7 notebooks in NotebookViewer.tsx
itself and accept a `name=` prop, so pages no longer need to
import notebook data. 7 pages + NotebookViewer.tsx.
Also updates scripts/README.md to document the registry pattern and
the new NVIDIA-NeMo/nemo-platform repo URL.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Signed-off-by: Lawrence Lane <llane@nvidia.com>
docs(fern): use NVIDIA global-theme + fix out-of-fern page imports
Contributor
|
The MkDocs → Fern migration left mkdocs.yml referenced as a hatch
force-include in both nemo-platform-ext and the SDK, breaking uv sync
across every Lint/Test job. The old docs workflow also still tried to
run `make -C docs publish`, which no longer exists.
Build fixes:
- Drop the mkdocs.yml force-include from nemo-platform-ext and SDK
pyproject.toml, and from the SDK post-generation generator.
- Replace the nemo docs CLI command to read .mdx (frontmatter-aware,
no mkdocs config); update both source and vendored test suites.
Generator fixes (so lint diffs stay clean):
- docs_generator.py emits Fern frontmatter for the CLI reference and
escapes `{`/`<` outside code fences for MDX safety.
- generate_config_docs.py writes config-reference.mdx with frontmatter.
- auth-tools.py writes permissions-reference.mdx with frontmatter and
Fern's <Note> component; tables now double-escape pipes.
- Update Makefile and lint-config-reference-docs.sh to point at .mdx.
- Add SPDX headers to fern notebook .ts files and styles.
Fern CI workflows (adapted from NVIDIA-NeMo/Gym for docs/fern/ layout):
- fern-docs-ci.yaml: `npm run check` on PRs.
- fern-docs-preview-build.yaml / -comment.yaml: split build/comment so
fork PRs run safely and previews still get a stable 🌿 comment.
- publish-fern-docs.yaml: publish on push to main or docs/v* tags.
- Delete the old .github/workflows/docs.yaml.
NOTE: the preview/publish workflows require an org-level DOCS_FERN_TOKEN
secret (from `fern token` for the nvidia Fern org).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Signed-off-by: Lawrence Lane <llane@nvidia.com>
lbliii
force-pushed
the
lbliii/fern-docs-port
branch
from
e99c711 to
8a455a0
Compare
Resolve conflict in docs/data-designer/index.mdx: keep the Fern <Cards>/<Card> structure from the migration and pick up main's DataDesigner version bump (0.5.7 → 0.6.0). main's "Move configurations" text was already present in the Fern migration card. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Lawrence Lane <llane@nvidia.com>
mckornfield
approved these changes
May 22, 2026
Contributor
mckornfield
left a comment
mckornfield
left a comment
There was a problem hiding this comment.
few more comments but since you're doing this as a public service, I don't see the point in holding you up on it. I can always do the fast follows or ask you about them haha
Contributor
There was a problem hiding this comment.
just curious, how does the new stuff handle "hidden" pages
| ## Job Credential Propagation | ||
|
|
||
| When a user submits a job (customization, evaluation, data generation), the job runs in a Kubernetes pod that needs to call {{platform_name}} APIs — to download datasets, upload results, and read secrets. The platform propagates the submitting user's identity into the job container so it operates with the user's permissions, not elevated service credentials. | ||
| When a user submits a job (customization, evaluation, data generation), the job runs in a Kubernetes pod that needs to call NeMo Platform APIs — to download datasets, upload results, and read secrets. The platform propagates the submitting user's identity into the job container so it operates with the user's permissions, not elevated service credentials. |
Contributor
There was a problem hiding this comment.
I assume this templating is also not something we do with fern? it's ok if so
Contributor
There was a problem hiding this comment.
There is some code that relies on this file existing to hide docs, I would just ask the agent to grep for mkdocs.yml
| path: ../../anonymizer/sdk-resources.mdx | ||
| - page: CLI Reference | ||
| path: ../../anonymizer/cli.mdx | ||
| - section: Guardrail Models |
Contributor
There was a problem hiding this comment.
I guess instead of hiding, the idea would be just not to include things in the ToC tree?
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.
No description provided.