Repository navigation
docs: add Recipes & Feature Benchmarks Fern surfaces - #10628
Conversation
Split recipe content into two linked docs surfaces: - Recipes: model-first deployment targets (13 model families, 33 targets) with landing-page filters, multi-target matrices, and per-target deploy/ smoke-test/benchmark instructions - Feature Benchmarks: feature-first evidence pages (6 comparisons + the KV Router A/B hands-on guide) with deployable control/treatment arms Backed by machine-readable catalogs (docs/recipes/_catalog/recipes.yaml, docs/benchmarks/_catalog/benchmarks.yaml) that serve humans, validation automation, and agentic harnesses. Pages verified against current recipe sources; no customer-visible placeholders — standards gaps tracked in the catalog gaps fields. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace the duplicated hero card with a short intro + 'Choose your deployment target' picker (GPU SKU x workload, pure CSS via :has()). All deploy/smoke-test/benchmark commands are now concrete per selected variant instead of parameterized prose; prerequisites become a checklist with variant-scoped HF token requirements; the selected target's row is highlighted in the results table. Picker CSS is generic (recipe-sku / recipe-usecase inputs + data-sku/data-usecase tags) for reuse on other multi-target recipe pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Apply the Kimi-K2.6 pilot design across the catalog: - 9 picker pages: SKU x workload (nemotron-3-ultra, nemotron-3-super, kimi-k2-6), SKU x topology (qwen3-235b-a22b-fp8), and single-axis pickers (llama-3-3-70b topologies, qwen3-32b-fp8 runtimes, glm-5-nvfp4 UCX/EFA, qwen3-32b disagg/KVBM, gpt-oss-120b agg/disagg) - 4 single-target pages use the degenerate static 'Deployment target' panel (kimi-k2-5, deepseek-v3-2-nvfp4, qwen3-vl-30b, qwen3-6-35b) - hero cards, recommendation cards, and prereq-grid cards removed everywhere; prerequisites are checklists; all commands concrete per selected variant; CSS gains a generic recipe-variant axis Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Parallel authoring left label drift in the target-picker fact strips (Trace/Traffic/Traffic fit/Workload all naming the same slot, plus Technique/Techniques, MoE/MoE backend, Goodput/SLA, Model/Checkpoint, GPUs / worker). Standardize on a fixed vocabulary: Checkpoint, Precision, GPUs, Workload, SLA, Techniques, plus specific backend labels. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Smoke-test sections said 'run a small request before benchmarking' — benchmark-first framing. Recipes are deployment-first: the test request verifies the deployment serves traffic. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per the deployment-first rule: Recipes and Feature Benchmarks separate cleanly in R1, with no recipe promoted out of an ablation study until R2 defines the promotion process (ownership, validation, benchmark sync). - Remove kimi-k2-5 (benchmark-first source: 4-arm ablation, unresolvable image tag), qwen3-6-35b (no kubectl-apply path; envsubst harness only), and qwen3-vl-30b (benchmark-derived; held back per no-promotion rule) from the Recipes surface — 10 model families / 30 targets remain - Their feature-benchmark pages stay; 'Related Recipe' sections become 'Winning Configuration' (deployable from arm assets; promotion deferred) - Catalog: cut entries moved to deferred_recipes with reasons; benchmark entries gain promotion_candidate markers - deepseek-v3-2-nvfp4 and qwen3-32b stay: kubectl-apply standalone today Source-repo packaging fixes tracked in #10626. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…no hero Apply the recipes design language to all six benchmark detail pages: - Delete the hero block (question was stated up to 4x: subtitle, hero paragraph, hero h2 rephrasing, Benchmark Question section — now asked once, in the subtitle) and the action-chip pseudo-TOC that duplicated Fern's on-page navigation - Headline finding moves into the intro in bold; Results becomes the first content section where numbers exist (omitted entirely otherwise) - Static 'Benchmark setup' panel (same component as recipes) absorbs the facts grid and the comparison-brief's Held-constant field - Vocabulary: 'Compared Arms'->'Compared Configurations', 'Treatment'->'Comparison' badges, 'Benchmark notes'->'Notes' Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
WalkthroughThis PR introduces a comprehensive documentation system for the NVIDIA Dynamo platform's feature benchmarks and deployment recipes. It adds two machine-readable YAML catalogs, landing pages with interactive filtering, six detailed benchmark documentation pages, and twelve recipe pages covering deployment guidance for specific model configurations. It also updates navigation and CSS styling to support the new catalog UI. ChangesBenchmark and Recipe Catalog System
A/B Benchmark Pages
Feature-Stack Benchmark Pages
Recipe Pages
🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/benchmarks/deepseek-v3-2-wideep-routing.mdx`:
- Line 92: Remove the internal Linear ticket reference "(DYN-2878)" from the
docs line that mentions `perf.yaml` and the `deepseek_v32` tokenizer; update the
sentence to simply state that older `transformers` versions (e.g.,
`transformers==4.57.6` used with `aiperf==0.6.0`) cannot load the `deepseek_v32`
tokenizer and cause AIPerf to surface "Failed to load tokenizer", without
including any internal ticket IDs.
In `@docs/benchmarks/qwen3-6-35b-feature-stack.mdx`:
- Line 24: Update the markdown link target that currently points to
"./embedding_cache.md" so it references the active benchmark doc
"qwen3-vl-embedding-cache.mdx"; locate the link text "Embedding Cache Benchmark"
or the literal "./embedding_cache.md" in the qwen3-6-35b-feature-stack.mdx
content and replace the href with "qwen3-vl-embedding-cache.mdx" to avoid the
stale/404 target.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: b913ebf5-7e9d-4723-9f3a-2b1ced7cb023
⛔ Files ignored due to path filters (1)
docs/assets/img/recipes/providers/zai-org.svgis excluded by!**/*.svg
📒 Files selected for processing (29)
docs/assets/img/recipes/providers/deepseek-ai.webpdocs/assets/img/recipes/providers/meta-llama.webpdocs/assets/img/recipes/providers/moonshotai.webpdocs/assets/img/recipes/providers/nvidia.webpdocs/assets/img/recipes/providers/openai.webpdocs/assets/img/recipes/providers/qwen.webpdocs/assets/img/recipes/providers/zai-org.webpdocs/benchmarks/README.mdxdocs/benchmarks/_catalog/benchmarks.yamldocs/benchmarks/deepseek-v3-2-wideep-routing.mdxdocs/benchmarks/kimi-k2-5-feature-stack.mdxdocs/benchmarks/llama-3-70b-topology.mdxdocs/benchmarks/qwen3-32b-kv-routing.mdxdocs/benchmarks/qwen3-6-35b-feature-stack.mdxdocs/benchmarks/qwen3-vl-embedding-cache.mdxdocs/index.ymldocs/recipes/README.mdxdocs/recipes/_catalog/recipes.yamldocs/recipes/deepseek-v3-2-nvfp4.mdxdocs/recipes/glm-5-nvfp4.mdxdocs/recipes/gpt-oss-120b.mdxdocs/recipes/kimi-k2-6.mdxdocs/recipes/llama-3-3-70b.mdxdocs/recipes/nemotron-3-super.mdxdocs/recipes/nemotron-3-ultra.mdxdocs/recipes/qwen3-235b-a22b-fp8.mdxdocs/recipes/qwen3-32b-fp8.mdxdocs/recipes/qwen3-32b.mdxfern/main.css
- Remove internal Linear ticket references (DYN-2878) from shipped pages per docs/AGENTS.md (no internal refs in customer-facing docs) - Replace the relative link to unregistered embedding_cache.md with a GitHub source link (page is not in docs/index.yml navigation) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Preview styling issue — root-caused and fixed for this PR. The earlier previews of this PR rendered without its custom CSS. Root cause, confirmed by experiment and by the Fern CLI source: the Fix in this PR (commit e41d255): PR previews skip the theme injection; production publishes keep it. The current preview now renders fully styled: https://nvidia-preview-4eeccd67-fe0e-4e96-b17f-00e683d6c4c1.docs.buildwithfern.com/dynamo/dev/recipes
|
…ders Hosted PR previews built with global-theme: nvidia serve the theme's stylesheet and drop the project css: list — any fern/main.css change renders unstyled in previews (first observed on #10628, the first main.css change since the theme injection landed in #10288). Skip the theme for non-main builds; production publishes keep it. The repo main.css already contains the NVIDIA branding rules, so unthemed previews remain visually faithful. If the next preview of this PR renders styled, this also confirms the theme masks project CSS on the production publish path — tracked for a separate fix (update the theme or make project css override it). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, qwen3-32b single target - Fix filter scroll-jump: hidden filter inputs were focusable 1x1 elements at the top of the form, so clicking any chip scrolled the page to the top; they are now display:none (label activation and :checked sibling selectors are unaffected) - Sidebar: hide Feature Benchmark detail pages from nav (their sidebar titles reverted to model-first framing; the landing rows are the real index — pages stay URL-accessible) and give both sections an explicit 'Browse All ...' first entry since section-header links don't read as clickable - Qwen3-32B: reduce to the single promoted target (disagg + KV router, the A/B winner) framed for multi-turn conversational traffic; the agg-kvbm walkthrough is now a Notes pointer (KVBM feature guide, not a validated target) and its 'deployment-only' tag no longer pollutes the landing filters; the unused Deployment-only chip is removed (29 targets) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove the agg-kvbm walkthrough pointer from the Qwen3-32B recipe and mark the catalog gap note accordingly. No docs re-add planned; source assets under recipes/qwen3-32b/vllm/agg-kvbm/ are untouched pending KVBM deprecation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
dagil-nvidia
left a comment
There was a problem hiding this comment.
Approving — strong format. Consistent templates across all 18 pages, same section order every time, and the two catalog landing pages give recipes and benchmarks a real front door. New models drop into a known shape. I read fern/main.css and the _catalog yaml to check the moving parts. The asks below are all non-blocking.
Add a page-authoring doc — the picker side is undocumented. The _catalog/*.yaml files have a documented schema header (the "stable contract"), which is great, but it only covers catalog metadata. Nothing documents how to add a page: the target-picker markup, the data-variant/data-sku/data-usecase attributes, or the step sequence (write MDX → add _catalog entry → wire docs/index.yml → patch main.css if a new axis value is introduced). recipes/CONTRIBUTING.md is about the deployment recipes and says nothing about the docs format. Extend the _catalog schema header or add a sibling docs/recipes/_catalog/README.md covering the page side.
Document the picker's CSS-coupled vocabulary. The hide/highlight rules in main.css hardcode every allowed value (agg, disagg, trtllm-agg, b200, hopper, chat, ...). A recipe with a new axis value (mi300 SKU, disagg-3node topology) renders the picker but filters nothing, because no CSS rule matches. List the supported values where the authoring doc above lives, and note that a new value requires a main.css edit.
Card hrefs: switch /dynamo/dev/... to relative paths. The catalog cards use absolute /dynamo/dev/ hrefs in JSX. Fern's version resolver won't rewrite them, so the first versioned cut (/dynamo/1.3.0/) points every card back at dev. Detail-page links already use relative ../ — cards should match.
Add hide-toc: true to the two catalog READMEs. They have custom card UIs, so the right-rail TOC adds clutter without navigation. benchmarks/README.mdx also uses <h2> for card titles, dumping every card name into that TOC. (layout: overview optional, widens the column for the grids.)
Note the picker↔workflow coupling in the PR. The picker only works because project CSS renders, which is what the fern-docs.yml preview-vs-main change protects. Flag it so nobody strips the workflow change later and silently flattens every recipe.
Confirm the 2045 CSS lines don't leak. Namespaced under dynamo-* (good) — worth one read to confirm nothing hits default Fern selectors.
Content (separate pass, optional): kimi-k2.5 Results table needs a concurrency column; nemotron-3-super missing the Day-0 caveat nemotron-3-ultra has; glm-5's "17–19K tok/s" headline sits above its measured 16,824 floor.
Verified clean, no asks: :has() degrades safe (older browsers show all variants stacked), hidden variants use display: none so the a11y tree stays clean, comparison tables dim with opacity (all rows stay readable), and labels have :focus-visible outlines.
nealvaidya
left a comment
There was a problem hiding this comment.
Broadly speaking, I have three main points of feedback:
-
Recipes should live in their own top-level docs tab rather than as a section in the main docs sidebar. Fern supports this directly via
tabs: https://buildwithfern.com/learn/docs/configuration/tabs -
I’d suggest breaking up the catalog manifests, especially
docs/recipes/_catalog/recipes.yaml, into multiple files that follow the same schema, with a small top-level index controlling ordering. This should reduce merge conflicts, make reviews easier, and give us a cleaner path to ownership and validation later. The same might make sense for benchmarks too as that catalog grows.For example, something like:
docs/recipes/_catalog/ README.md index.yaml schema.json recipes/ kimi-k2-6.yaml nemotron-3-ultra.yaml qwen3-32b.yamlWhere
index.yamlis only responsible for ordering/inclusion:schema_version: 1 recipes: - kimi-k2-6 - nemotron-3-ultra - nemotron-3-super
Each recipe file would contain one recipe object, and
schema.jsonwould define the object schema. A validator can then check IDs, paths, related benchmarks, duplicate entries, and index/file consistency. -
Removing the global NVIDIA theme is fine temporarily while this is in development/preview, but we should not ship to production without it. The global NVIDIA theme is a hard requirement for a consistent docs.nvidia.com experience. If our custom CSS needs changes that the global theme does not currently support, we should work with the docs org to either upstream those customizations or find a supported extension point.
…jump Three landing-page filter fixes from review: - Remove 4 filter chips that matched zero cards after the R1 scope cut (runtime: Dynamo; technique: Embedding cache, Frontend decoding; workload: Multimodal reuse) — their only matches were deferred recipes. - Add a CSS-only empty state: a message painted under the card grid that the cards cover until a cross-dimension filter combo hides them all. - Fix the focus jump to top when clicking a filter: hide the radio inputs with display:none instead of visually-hidden positioning, so activating a label no longer scrolls focusable off-screen inputs into view. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Card hrefs → relative .mdx/.md paths so versioned cuts resolve correctly (Fern rewrites them to version-aware slugs at build time) - hide-toc + layout:overview on the two catalog READMEs (custom card UIs made the right-rail TOC noise) - Scope .feature-* icon pseudo-elements under .dynamo-feature-symbol so the short class names can't collide with default Fern selectors - Add docs/recipes/_catalog/README.md: page-authoring guide covering the picker markup, data-* attributes, the CSS-coupled vocabulary, and the 'new axis value needs a main.css edit' coupling - Content: kimi-k2.5 Results gains a concurrency column; nemotron-3-super gains the Day-0 dev-image caveat (it runs the same dev image as ultra); glm-5 headline corrected (16.8K standard / 19K EFA, was '17-19K') Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per review (Neal Vaidya) + Ben/Harry: Recipes becomes a dedicated top-level Fern tab instead of a section in the main docs sidebar, so it doesn't compete for sidebar space and has a clean home as the catalog grows. Feature Benchmarks stays in the main docs sidebar for now. - Add a tabs: block (Documentation + Recipes) to docs/index.yml - Wrap all existing sections under '- tab: docs' with skip-slug: true so every existing doc URL (incl. /benchmarks) stays at root — without skip-slug the docs tab prefixes everything with /documentation/ and breaks the whole site's internal links - Move the Recipes tree under '- tab: recipes' (slug /recipes), flattened so the tab doesn't show a redundant 'Recipes' section header Verified: /recipes, /recipes/<page>, /benchmarks, and existing doc URLs all 200; broken-links back to the 6 pre-existing errors; recipe<->benchmark cross-links resolve (Fern resolves .mdx links by file, not URL). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…dya review #2) Replace the monolithic recipes.yaml / benchmarks.yaml with one file per entry + an ordering index + a JSON schema + a validator, to cut merge conflicts and give a cleaner per-entry ownership/validation path. docs/recipes/_catalog/ index.yaml # ordering + inclusion (10 active + 3 deferred) schema.json # JSON Schema (draft 2020-12), one recipe object recipes/<id>.yaml # one object per file, verbatim validate.py # validates BOTH catalogs docs/benchmarks/_catalog/{index.yaml,schema.json,benchmarks/<id>.yaml} validate.py checks index<->file correspondence, id/filename match, no dups, schema conformance, page/asset path resolution, and cross-catalog referential integrity; exits non-zero on failure. Stdlib-only with graceful degradation (prefers pyyaml+jsonschema, falls back to a builtin parser + required-keys check). All entries preserved verbatim (round-trip diff: 0 mismatches). Wiring the validator into CI is a tracked follow-up. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Regression from the relative-href change (#10628 review): relative .mdx hrefs inside JSX <a> tags break MDX parsing in Fern 5.37.10 — the parser demotes the card block to text and smartypants then mangles the quotes, so the Recipes and Feature Benchmarks landings rendered as raw markup. Confirmed the tradeoff empirically: - relative '<slug>.mdx' in JSX href -> breaks MDX JSX parsing - bare '<slug>' / 'benchmarks/<slug>' -> renders, but the file-based broken-links check flags them (URL-relative != file-relative) - absolute '/dynamo/dev/...' -> renders AND passes broken-links Absolute is the only form that both renders and passes CI in this Fern version. Versioned-snapshot correctness (Dan Gil's original ask) is a release-workflow concern (rewrite /dev/ -> /vX.Y.Z/ alongside the existing github-link rewrite), not fixable in page markup without breaking rendering — re-tracked as a follow-up. Also drops the optional layout:overview from the two READMEs (not the cause, but minimizes frontmatter variables). hide-toc retained. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ations' The abstract 'recipe targets' label needed decoding; 'deployable configurations' is self-evident. (Per Ben review.) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The summary panel read as a jumble — labels (CHECKPOINT, PRECISION...) and their values sat inline with similar weight, so adjacent facts blurred together. Restyle to a responsive grid of stacked cells: small muted uppercase label above a prominent dark value, columns aligned. Far more scannable. (Per Ben review.) Applies to both the multi-target picker summary and the single-target static panel. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…-benchmarks-fern # Conflicts: # docs/index.yml
Sentinel-only probe to confirm, via a CI hosted preview, that a custom Fern mdx-component can inject a <style> block that survives the published build (the path DataDesigner uses for the same global-theme: nvidia / no-css constraint). NOT the final styling — RecipeStyles.tsx carries a throwaway sentinel rule (crimson picker title + a :has() ::after marker) and will be replaced with the real .dynamo-* stylesheet once the mechanism is confirmed. - fern/components/RecipeStyles.tsx: new server component, <style> via dangerouslySetInnerHTML (mirrors NVIDIA-NeMo/DataDesigner BlogCard). - docs/recipes/kimi-k2-6.mdx: <RecipeStyles /> after frontmatter, no import (ambient mdx-components registration). - fern/fern.config.json: pin 5.37.10 -> 5.41.1. Local fern docs dev cannot render custom mdx-components on any version, but the wrapper honors this pin for the published build; 5.41.1 matches DataDesigner's proven-good version. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The hosted preview confirmed custom mdx-components must be IMPORTED — ambient <RecipeStyles /> logged "Unsupported JSX tag" in both local dev and the published build. Per Fern's custom-react-components docs, import with the @/ prefix (resolves to fern/ root, transformed to a relative path at publish time): @/components/RecipeStyles -> fern/components/. Local `fern docs dev` still can't render custom components, but the published build (CI preview) can, so this is verified there. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mechanism verified on the CI hosted preview (the @/ import renders the
component's <style> in the published build). This moves the real styling
off the theme-masked css: path:
- fern/main.css: drop the ~2,135-line .dynamo-* block (recipe catalog,
variant picker, :has() filter rules, comparison tables, mobile). Keep
the base NVIDIA/.fern-*/footer/hero rules (now 815 lines).
- fern/components/RecipeStyles.tsx: carry that full stylesheet, injected
via <style dangerouslySetInnerHTML> (replaces the crimson sentinel).
- 17 pages (10 recipes + 6 benchmarks + 2 landing READMEs): add
`import { RecipeStyles } from "@/components/RecipeStyles";` +
<RecipeStyles /> after frontmatter (kimi-k2-6 already had it).
fern check + fern docs broken-links both clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The catalog had 5 single-select AND-facets over only 10 recipes, so plausible combinations (e.g. DeepSeek + Aggregated + Agentic coding) dead-ended on "No recipes match" — and a pure-CSS filter can't gray out incompatible chips. Drop Technique and Workload as filters (they were the sparse, dead-end-prone dimensions); each card already shows its workload as a tag and its technique in the summary, so the info stays on the cards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
From a fresh-eyes review of all 18 pages (cross-checked against the real recipes/ manifests). All findings re-verified against the manifests. Command/factual fixes: - Image tag 1.2.0 -> 1.2.1 (deepseek, gpt-oss x2, llama-3-3-70b) — manifests pin 1.2.1. - deepseek recipe: replace broken `tmux a -t benchmark` monitor with `kubectl logs -f -l job-name=disagg-kv-dsv32-nvfp4-bench` (perf is a Job, no tmux). - deepseek benchmark: fix run mechanism/results path (K8s Job -> model-cache PVC /model-cache/perf/, not tmux/perf-cache). - gpt-oss: disagg deploy-watch selector part-of -> nvidia.com/dynamo-graph-deployment-name=gpt-oss-disagg (part-of label absent). - gpt-oss: relabel agg "WideEP" -> "EP4 + attention-DP" (CUTLASS backend, not WIDEEP). - kimi-k2-5 benchmark: placeholder my-tag -> <IMAGE_TAG> (matches manifests). - qwen3-32b: background the smoke-test port-forward (+ `&` and `sleep 3`) so the curl runs. Results/wording integrity: - qwen3-vl benchmark: cite results provenance (recipe README) + drop misleading "average improvement"; fix run-benchmark.sh description (one mode per invocation). - kimi-k2-5: frame results rows as per-config Pareto operating points (approximate). - llama-3-70b benchmark: relabel Reproduce command as representative (perf.yaml authoritative) + add TPS/GPU apples-to-apples caveat. Landing/UX: - benchmarks landing: drop the legacy `kv-router-ab-testing` card (outside the new catalog; legacy page kept in nav, revisit in R2). - RecipeStyles.tsx: add the missing `.winner` (green) and `.treatment` (blue) role-pill styles. Source-README bugs (tmux, part-of selector) are inherited from recipes/.../README.md and need a separate recipes/ fix — out of R1 scope. fern check + broken-links clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The pre-commit check (and thus pre-merge-status-check) was failing on the catalog validator since it was added: `black` 23.1.0 reformatted it and `check-shebang-scripts-are-executable` flagged its `#!/usr/bin/env python3` shebang on a non-executable file. Applied the pinned black formatting and set the executable bit. Validator output unchanged (13 recipes / 6 benchmarks, all checks pass); flake8 (max-line-length=88, E501 ignored) is clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…afe) Addresses Dan's review: absolute /dynamo/dev/ card hrefs aren't rewritten by Fern's version resolver, so the first versioned cut would point every card back at dev. The earlier relative-href parser break was on Fern 5.37.10; on the now-pinned 5.41.1, file-relative `./<slug>.mdx` hrefs in the JSX cards resolve cleanly (matching the detail-page link convention) — fern check + fern docs broken-links both pass. Converted all 10 recipe + 6 benchmark cards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… keeps rich cards) Relative .mdx hrefs version-rewrite correctly but Fern flattens the rich JSX card (strips className/children). Absolute /dynamo/dev/ keeps the card but isn't version-rewritten. Bare relative slugs (href="<slug>") avoid both: not a .mdx file link so the card is left intact, and the browser resolves them against the current versioned URL (both READMEs are at /<section>/browse). fern check + broken-links pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…iable) Investigated Dan's version-safety ask on the hosted build. None of the relative forms work for the rich JSX cards: relative .mdx version-rewrites the URL but Fern flattens the card (strips className/children); bare relative slugs keep the card but fail fern docs broken-links (24 errors). Absolute /dynamo/dev/ is the only form that both renders the rich cards and passes CI. The version-safe-rich-card gap is a real Fern limitation to raise with the docs team; absolute is correct for R1 (dev only). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…n-safe) Preview eval (recipes landing only). Each card is now a <div> (keeps its data-* filter attrs and rich markup, so Fern never reprocesses/flattens it) with one inner Fern-resolved link (href="./<slug>.mdx") stretched over the whole tile via CSS. Result: the href gets version-rewritten while the card keeps its styling, layout, and pure-CSS filter, and the whole tile stays clickable. broken-links clean. (The 848 fern check --warnings are pre-existing versioned-snapshot redirect debt — present on HEAD without this change.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Applies design #1 (verified on recipes) to the 6 benchmark cards: row is now a <div> with one inner Fern-resolved link (./<slug>.mdx) stretched over the tile, so hrefs version-rewrite while the rich card + whole-tile click are preserved. Both catalog landings are now version-safe. fern check 0 errors; broken-links clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…-benchmarks-fern # Conflicts: # docs/index.yml
Summary
Adds two linked documentation surfaces to the Fern docs site, replacing the ad hoc recipe README experience:
docs/recipes/, top-level nav): model-first deployment targets. A landing page with working pure-CSS filters (provider / runtime / hardware / technique / workload) over 10 model families, and detail pages covering 30 deployable targets. Multi-target pages use a variant picker (GPU SKU × workload, or single-axis topology/runtime/build) — the user picks their target and every command on the page (deploy, smoke test, benchmark) becomes concrete and copy-pasteable. Single-target pages use the same panel statically.docs/benchmarks/, top-level nav): feature-first evidence pages. Six comparisons with deployable control/treatment configurations, results tables where sources publish numbers, and reproduce instructions — plus the existing KV Router A/B hands-on guide relocated into the section.Both surfaces are backed by machine-readable catalogs (
docs/recipes/_catalog/recipes.yaml,docs/benchmarks/_catalog/benchmarks.yaml) that serve as the stable contract for humans, validation automation, and agentic harnesses: what exists, how to deploy it, how to benchmark it, expected performance, and known gaps.Design principles applied
deferred_recipescarries reasons); source-packaging issues are tracked in Recipes audit: several recipes are packaged benchmark-first, not deployment-first #10626. Therecipes/source tree is intentionally unchanged.:has()), no JS, dark mode supported.Verification
fern checkclean;fern docs broken-linksreports only the 6 errors that pre-exist onmain(verified by stashing).fern docs dev; light + dark mode inspected; every filter chip, picker control, anchor, and cross-link click-verified; all catalog asset paths verified to exist in the tree.recipes/**sources (this surfaced several stale upstream README claims, noted in Recipes audit: several recipes are packaged benchmark-first, not deployment-first #10626 and the catalog gap fields).Included CI change: theme-skip for PR previews
Important
The variant picker depends on project CSS rendering, which the
fern-docs.ymlchange protects. PR previews skip theglobal-theme: nvidiainjection sofern/main.cssrenders; if that workflow change is later reverted without first removingcssfrom the production theme, every recipe page silently flattens (picker shows but filters nothing, cards lose layout). Do not strip the workflow change in isolation.This PR also modifies
.github/workflows/fern-docs.ymlso PR preview builds skip theglobal-theme: nvidiainjection (production publishes keep it). Reason: the Fern CLI's theme merge gives the theme'scssabsolute precedence over the projectcss:list (css: "global"inthemeEligibleFields.ts— list fields are replaced, not merged), so previews of anyfern/main.csschange render unstyled. This PR is the firstmain.csschange since the theme injection landed (#10288), which is why it surfaced now. The change is bundled here because without it this PR cannot be visually reviewed; the current preview renders correctly with it. Details: PR comment.Merge dependency to be aware of: the production publish path still applies the theme, so the new styles will not reach docs.dynamo.nvidia.com after merge until the
cssfield is removed from thenvidiatheme definition in the Fern dashboard (one-time central change; the repomain.cssalready contains all branding rules the theme carries). Until that happens, the live dev site will show the new pages with production's current styling.Review feedback addressed
Dan Gil (approved): card hrefs switched to relative paths (version-safe);
hide-toc/layout:overviewon the two catalog READMEs;.feature-*icon CSS scoped under.dynamo-feature-symbol(no default-selector leak); newdocs/recipes/_catalog/README.mdpage-authoring guide documenting the picker markup,data-*attributes, and the CSS-coupled vocabulary; content fixes (kimi-k2.5 concurrency column, nemotron-3-super Day-0 caveat, glm-5 headline).Neal Vaidya: Recipes moved to its own top-level tab (Documentation + Recipes), with
skip-slug: trueon the docs tab so existing URLs are unchanged. Feature Benchmarks stays in the main docs sidebar for now. Catalog-split into per-recipe files (Neal's 2nd point) and the production-theme decision (3rd point) are tracked as follow-ups below.Known follow-ups (tracked, not blocking)
/dynamo/dev/...; fine on dev, needs a version-safe strategy before release snapshots (markdown links are already version-safe).docs/assets/img/recipes/providers/carried from the earlier prototype branch; confirm brand-asset provenance.docs/benchmarks/embedding_cache.mdoverlaps the Qwen3.6 feature-stack page; decide redirect/retire.cssfrom thenvidiatheme definition (or upstream thedynamo-*rules into it) so project CSS publishes. The preview theme-skip is the dev-only half of this.recipes.yamlinto per-recipe files + anindex.yaml(ordering) +schema.json+ a validator, to cut merge conflicts as the catalog grows. Deferred to a follow-up PR.cssfrom thenvidiaglobal theme (Fern dashboard, see docs(fern): enable NVIDIA global theme and upgrade Fern CLI to 5.37.10 #9967 owner) so project CSS publishes to production; then the preview theme-skip can optionally be reverted.🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes