Skip to content

docs(fern): inject NVIDIA global-theme at publish time so local preview works (#10073) - #10288

Merged
zhongdaor-nv merged 1 commit into
mainfrom
zhongdaor/fern-local-theme
Jun 10, 2026
Merged

zhongdaor-nv merged 1 commit into
mainfrom
zhongdaor/fern-local-theme

Conversation

@zhongdaor-nv

@zhongdaor-nv zhongdaor-nv commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

fern/docs.yml set global-theme: nvidia, a private theme in Fern's registry (org nvidia). When a contributor runs fern docs dev while logged into a Fern org (or with FERN_TOKEN set), the CLI fetches that private theme with their token, gets HTTP 403, and renders a blank local preview. This is the breakage reported in #10073.

This PR removes global-theme from the committed config so fern docs dev works for all contributors, and injects the theme at publish time so production docs keep the NVIDIA branding.

Root cause

The Fern CLI (5.37.10) resolves global-theme like this:

let token = (await cit())?.value ?? process.env.FERN_TOKEN;
if (token == null) return warn("theme will not be applied in dev mode"), config;  // no creds -> graceful skip
return fetchTheme({ organization: "nvidia", token });  // has creds -> fetch private theme -> 403 for non-nvidia tokens
  • No Fern credentials at all → warns and skips the theme → preview works (just no NVIDIA branding).
  • Logged into any Fern org / FERN_TOKEN set → fetches nvidia theme with that token → 403 → Failed to read docs configuration. Rendering blank page.

The second case is common (many contributors have run fern login), so the documented fern docs dev flow is broken for them.

Fix

  1. fern/docs.yml — remove global-theme: nvidia from the committed config (with an explanatory comment). The branding inlined in docs.yml (colors, typography, logo, main.css) still renders locally.
  2. .github/workflows/fern-docs.yml — inject global-theme: nvidia via yq in the step that assembles the production docs.yml on the docs-website branch. This single injection covers the PR-preview and main-publish paths; the version-release job inherits it from the committed docs-website docs.yml, so production is unchanged.

Validation

Ran fern docs dev in a clean checkout with a non-nvidia FERN_TOKEN (reproducing the reported scenario):

before (with global-theme) after (this PR)
Fetching global theme "nvidia" yes no
HTTP 403 yes no
Failed to read docs configuration. Rendering blank page. yes no
localhost:3000 preview blank renders correctly

Confirmed the CI injection (yq -i '.global-theme = "nvidia"' docs.yml) restores the theme for production builds.

Fixes #10073.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Chores
    • Improved documentation preview experience by moving the NVIDIA theme configuration from source to the production publishing workflow, allowing contributors to preview documentation locally without requiring additional credentials.

@zhongdaor-nv
zhongdaor-nv requested a review from a team as a code owner June 3, 2026 21:27
@coderabbitai

coderabbitai Bot commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Walkthrough

This PR resolves external contributor build failures by decoupling the NVIDIA theme requirement from local development. The global-theme: nvidia setting is removed from the committed fern/docs.yml config and instead injected via workflow during publication, allowing local fern docs dev to work without a private theme token.

Changes

Theme configuration and deployment

Layer / File(s) Summary
Move NVIDIA theme to workflow injection
fern/docs.yml, .github/workflows/fern-docs.yml
fern/docs.yml removes hardcoded global-theme: nvidia and replaces it with comments explaining the theme is intentionally omitted for local builds and injected at publish time. The workflow "Update docs.yml preserving products" step adds a yq command to inject global-theme: nvidia into the checked-out docs configuration during deployment.

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: removing global-theme from the committed config and injecting it at publish time to fix the local preview issue.
Linked Issues check ✅ Passed The PR fully addresses the requirements from issue #10073: restores local preview capability for external contributors by removing the private theme from committed config, ensures production branding via CI injection, and validates the fix.
Out of Scope Changes check ✅ Passed All changes are directly scoped to fixing the documented issue: modifications to fern/docs.yml and .github/workflows/fern-docs.yml align with the objective of making local preview work while preserving production branding.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check ✅ Passed The PR description is comprehensive and well-structured, covering overview, root cause analysis, fix details, and validation results.

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


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@github-actions

github-actions Bot commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

…ew works

The committed fern/docs.yml set `global-theme: nvidia`, a private theme in
Fern's registry (org: nvidia). When a contributor runs `fern docs dev` while
logged into a Fern org or with FERN_TOKEN set, the CLI fetches the private
theme with their token, receives HTTP 403, and renders a blank local preview
(`Failed to read docs configuration. Rendering blank page.`). Contributors with
no Fern credentials at all only get a warning, but the common logged-in case is
broken — this is the failure reported in #10073.

Remove `global-theme` from the committed config so `fern docs dev` works for all
contributors (with or without a token), and inject it at publish time in the
Fern Docs workflow, in the step that assembles the production docs.yml on the
docs-website branch. That single injection covers both the PR preview and the
main publish paths; the version-release job inherits it from the committed
docs-website docs.yml, so production keeps the NVIDIA branding.

Fixes #10073.

Signed-off-by: zhongdaor <zhongdaor@nvidia.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

LGTM

@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. Drops global-theme: nvidia from the source docs.yml and re-injects it at publish time so external contributors can run fern docs dev without the private NVIDIA theme 403'ing the local preview (#10073). Doc-surface change is clean.

@zhongdaor-nv
zhongdaor-nv merged commit 9e44d9a into main Jun 10, 2026
105 checks passed
@zhongdaor-nv
zhongdaor-nv deleted the zhongdaor/fern-local-theme branch June 10, 2026 19:20
Broduker pushed a commit to Broduker/dynamo that referenced this pull request Jun 12, 2026
…ew works (ai-dynamo#10073) (ai-dynamo#10288)

Signed-off-by: zhongdaor <zhongdaor@nvidia.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: shenls <shenlinshan@kanzhun.com>
BenHamm added a commit that referenced this pull request Jun 12, 2026
…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>
yao531441 pushed a commit to yao531441/dynamo that referenced this pull request Jun 24, 2026
…ew works (ai-dynamo#10073) (ai-dynamo#10288)

Signed-off-by: zhongdaor <zhongdaor@nvidia.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

This branch was previously deployed

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fern docs dev broken for external contributors after global-theme: nvidia addition

4 participants