Skip to content

docs: add Recipes & Feature Benchmarks Fern surfaces - #10628

Merged
BenHamm merged 31 commits into
mainfrom
codex/recipes-feature-benchmarks-fern
Jun 16, 2026
Merged

BenHamm merged 31 commits into
mainfrom
codex/recipes-feature-benchmarks-fern

Conversation

@BenHamm

@BenHamm BenHamm commented Jun 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds two linked documentation surfaces to the Fern docs site, replacing the ad hoc recipe README experience:

  • Recipes (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.
  • Feature Benchmarks (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

  • Deployment-first. Recipes are packaged for serving, not timing: deploy → verify (test request) → benchmark, in that order. Three benchmark-derived recipes (kimi-k2.5, qwen3.6-35b, qwen3-vl-30b) are deliberately deferred until the benchmark→recipe promotion process is defined (catalog deferred_recipes carries reasons); source-packaging issues are tracked in Recipes audit: several recipes are packaged benchmark-first, not deployment-first #10626. The recipes/ source tree is intentionally unchanged.
  • Recipes vs. Feature Benchmarks separate cleanly. Comparison-only configurations live on benchmark pages, never as recipe targets. Benchmark winners are marked as promotion candidates in the catalog, not silently mirrored.
  • No customer-visible placeholders. Missing expected performance / benchmark sections are omitted, with gaps tracked in the catalogs.
  • One design system. Both surfaces share the target-picker/setup-panel component family and a fixed fact vocabulary (Checkpoint / Precision / GPUs / Workload / SLA / technique labels); pure CSS (:has()), no JS, dark mode supported.

Verification

  • fern check clean; fern docs broken-links reports only the 6 errors that pre-exist on main (verified by stashing).
  • All pages return 200 on 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.
  • All page content was verified line-by-line against current 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.yml change protects. PR previews skip the global-theme: nvidia injection so fern/main.css renders; if that workflow change is later reverted without first removing css from 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.yml so PR preview builds skip the global-theme: nvidia injection (production publishes keep it). Reason: the Fern CLI's theme merge gives the theme's css absolute precedence over the project css: list (css: "global" in themeEligibleFields.ts — list fields are replaced, not merged), so previews of any fern/main.css change render unstyled. This PR is the first main.css change 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 css field is removed from the nvidia theme definition in the Fern dashboard (one-time central change; the repo main.css already 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:overview on the two catalog READMEs; .feature-* icon CSS scoped under .dynamo-feature-symbol (no default-selector leak); new docs/recipes/_catalog/README.md page-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: true on 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)

  • Raw HTML card/hero hrefs hardcode /dynamo/dev/...; fine on dev, needs a version-safe strategy before release snapshots (markdown links are already version-safe).
  • Provider logos under docs/assets/img/recipes/providers/ carried from the earlier prototype branch; confirm brand-asset provenance.
  • Legacy docs/benchmarks/embedding_cache.md overlaps the Qwen3.6 feature-stack page; decide redirect/retire.
  • Production theme (Neal ci: update container registry location #3): keep the global NVIDIA theme for prod; remove css from the nvidia theme definition (or upstream the dynamo-* rules into it) so project CSS publishes. The preview theme-skip is the dev-only half of this.
  • Catalog split (Neal ci: update trigger token #2): break recipes.yaml into per-recipe files + an index.yaml (ordering) + schema.json + a validator, to cut merge conflicts as the catalog grows. Deferred to a follow-up PR.
  • Remove css from the nvidia global 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.
  • When the documentation-structure DEP (DEP: Documentation Structure Overhaul enhancements#89) lands, the two sections relocate within the new tree (Recipes is already slotted under Getting Started in the current draft); this is a nav-only change.

🤖 Generated with Claude Code


Open in Devin Review

Summary by CodeRabbit

Release Notes

  • Documentation
    • Added comprehensive Feature Benchmarks section showcasing performance comparisons across various model configurations and deployment topologies.
    • Added Recipes section with detailed deployment guides for multiple production model setups.
    • Introduced interactive recipe filtering UI to help users discover and compare deployment options.
    • Expanded documentation navigation with new organized categories for easier discovery.

BenHamm and others added 7 commits June 11, 2026 12:50
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>
@BenHamm
BenHamm requested a review from a team as a code owner June 11, 2026 23:04
@github-actions github-actions Bot added docs documentation Improvements or additions to documentation labels Jun 11, 2026
@github-actions

github-actions Bot commented Jun 11, 2026 •

Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 potential issues.

Open in Devin Review

Comment thread docs/recipes/deepseek-v3-2-nvfp4.mdx Resolved
@coderabbitai

coderabbitai Bot commented Jun 11, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Walkthrough

This 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.

Changes

Benchmark and Recipe Catalog System

Layer / File(s) Summary
Benchmark catalog and landing page
docs/benchmarks/_catalog/benchmarks.yaml, docs/benchmarks/README.mdx
Defines 6 benchmark records (id, page, claim, features, hardware, arms with deploy/perf paths, results, related recipes) and a feature benchmarks landing page with SVG icons, technique cards, and indexed benchmark grid.
Recipe catalog and landing page
docs/recipes/_catalog/recipes.yaml, docs/recipes/README.mdx
Defines recipe and deferred-recipe records (model, targets, techniques, expected performance, gaps) and an interactive recipes landing page with filterable model cards and empty-state messaging.
Navigation and CSS styling
docs/index.yml, fern/main.css
Adds Recipes and Feature Benchmarks navigation sections and extensive CSS for recipe/benchmark catalog UI (filters, pickers, cards, tables, comparison grids, mobile responsive layout).

A/B Benchmark Pages

Layer / File(s) Summary
KV routing and embedding cache A/B benchmarks
docs/benchmarks/qwen3-32b-kv-routing.mdx, docs/benchmarks/deepseek-v3-2-wideep-routing.mdx, docs/benchmarks/qwen3-vl-embedding-cache.mdx
Three A/B experiments comparing baseline vs optimized configurations (disaggregated KV routing, WideEP, embedding cache) with setup, configuration tables, reproduction commands, and promotion to related recipes.

Feature-Stack Benchmark Pages

Layer / File(s) Summary
Progressive feature composition benchmarks
docs/benchmarks/kimi-k2-5-feature-stack.mdx, docs/benchmarks/qwen3-6-35b-feature-stack.mdx, docs/benchmarks/llama-3-70b-topology.mdx
Three benchmarks demonstrating feature stacks (KV routing + Eagle3 + offload) and topology variants with results tables, configuration comparisons, and reproduction guidance.

Recipe Pages

Layer / File(s) Summary
Single-variant deployment recipes
docs/recipes/deepseek-v3-2-nvfp4.mdx, docs/recipes/glm-5-nvfp4.mdx, docs/recipes/llama-3-3-70b.mdx, docs/recipes/qwen3-32b.mdx
Four recipes for models with one or two deployment topologies, covering prerequisites, namespace setup, model-cache preparation, per-variant deploy commands, smoke tests, and AIPerf benchmark workflows.
Multi-variant deployment recipes
docs/recipes/gpt-oss-120b.mdx, docs/recipes/kimi-k2-6.mdx, docs/recipes/qwen3-32b-fp8.mdx, docs/recipes/qwen3-235b-a22b-fp8.mdx, docs/recipes/nemotron-3-super.mdx
Five recipes with interactive target pickers (GPU SKUs × use-case or topology combinations) describing checkpoint selection, per-variant deployment/benchmarking workflows, performance tables, and operational notes.
Flagship large-model recipes
docs/recipes/nemotron-3-ultra.mdx
Recipe for 550B model with GPU/workload target picker, model-cache setup, aggregated MTP and disaggregated fallback topologies, smoke test, Moontrace-based benchmarking, and performance tables.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: add Recipes & Feature Benchmarks Fern surfaces' clearly and concisely describes the main change: adding two new documentation surfaces (Recipes and Feature Benchmarks) to the Fern docs site.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description check ✅ Passed The PR description is comprehensive, well-structured, and addresses all required sections including overview, details, design principles, verification steps, and known follow-ups.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 0d3b170 and e6b3ea5.

⛔ Files ignored due to path filters (1)
  • docs/assets/img/recipes/providers/zai-org.svg is excluded by !**/*.svg
📒 Files selected for processing (29)
  • docs/assets/img/recipes/providers/deepseek-ai.webp
  • docs/assets/img/recipes/providers/meta-llama.webp
  • docs/assets/img/recipes/providers/moonshotai.webp
  • docs/assets/img/recipes/providers/nvidia.webp
  • docs/assets/img/recipes/providers/openai.webp
  • docs/assets/img/recipes/providers/qwen.webp
  • docs/assets/img/recipes/providers/zai-org.webp
  • docs/benchmarks/README.mdx
  • docs/benchmarks/_catalog/benchmarks.yaml
  • docs/benchmarks/deepseek-v3-2-wideep-routing.mdx
  • docs/benchmarks/kimi-k2-5-feature-stack.mdx
  • docs/benchmarks/llama-3-70b-topology.mdx
  • docs/benchmarks/qwen3-32b-kv-routing.mdx
  • docs/benchmarks/qwen3-6-35b-feature-stack.mdx
  • docs/benchmarks/qwen3-vl-embedding-cache.mdx
  • docs/index.yml
  • docs/recipes/README.mdx
  • docs/recipes/_catalog/recipes.yaml
  • docs/recipes/deepseek-v3-2-nvfp4.mdx
  • docs/recipes/glm-5-nvfp4.mdx
  • docs/recipes/gpt-oss-120b.mdx
  • docs/recipes/kimi-k2-6.mdx
  • docs/recipes/llama-3-3-70b.mdx
  • docs/recipes/nemotron-3-super.mdx
  • docs/recipes/nemotron-3-ultra.mdx
  • docs/recipes/qwen3-235b-a22b-fp8.mdx
  • docs/recipes/qwen3-32b-fp8.mdx
  • docs/recipes/qwen3-32b.mdx
  • fern/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>
@BenHamm

BenHamm commented Jun 11, 2026 •

Copy link
Copy Markdown
Contributor Author

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 global-theme: nvidia injected at build time (#10288) replaces the project css: list — css is a theme-eligible field with policy "global" ("theme value always wins; local docs.yml cannot override it", see packages/cli/configuration/src/docs-yml/themeEligibleFields.ts in fern-api/fern). This PR is the first fern/main.css change since the theme era began, which is why nobody had hit it.

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

⚠️ Remaining production issue (pre-merge decision needed): the publish path on main still injects the theme, so merged main.css changes will NOT reach docs.dynamo.nvidia.com until the theme is addressed. Cleanest fix: remove the css field from the nvidia global theme definition (in FDR/Fern dashboard, set up in #9967) — per the CLI merge semantics, when the theme doesn't define a field the local value survives, and this repo's main.css already contains all the NVIDIA branding rules the theme's css carries. Alternative: update the theme's css asset whenever main.css changes (couples every styling PR to a theme update — not recommended).

…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>
BenHamm and others added 2 commits June 12, 2026 11:41
…, 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 dagil-nvidia left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 nealvaidya left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Broadly speaking, I have three main points of feedback:

  1. 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

  2. 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.yaml
    

    Where index.yaml is 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.json would define the object schema. A validator can then check IDs, paths, related benchmarks, duplicate entries, and index/file consistency.

  3. 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.

BenHamm and others added 4 commits June 13, 2026 21:45
…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>
BenHamm and others added 4 commits June 13, 2026 22:52
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
BenHamm and others added 12 commits June 15, 2026 14:16
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
@BenHamm
BenHamm merged commit b63c086 into main Jun 16, 2026
158 of 160 checks passed
@BenHamm
BenHamm deleted the codex/recipes-feature-benchmarks-fern branch June 16, 2026 18:38

This branch was previously deployed

1 inactive deployment
GITLAB — ad3c7ec0 Deployed Jun 16, 2026 by copy-pr-bot[bot] via Trigger CI Pipeline #31417
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

actions docs documentation Improvements or additions to documentation size/XXL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants