Skip to content

feat: serve Nebari Classic docs from classic.nebari.dev - #735

Merged
jbouder merged 1 commit into
mainfrom
731-classic-subdomain
Sep 25, 2026
Merged

jbouder merged 1 commit into
mainfrom
731-classic-subdomain

Conversation

@jbouder

@jbouder jbouder commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Closes #731, closes #732, closes #733

Summary

This builds the Nebari Classic docs as their own site from the same Astro project (option 1 in #731) and serves it from https://classic.nebari.dev.

Two sites, one project

  • DOCS_SITE=classic switches astro.config.mjs to the Classic site: its srcDir is docs/classic/, its publicDir is docs/classic/public/, it writes to dist-classic/, and it has its own sidebar and title. Components and styles in src/ are shared.
  • The Classic content moved from src/content/docs/classic/ to classic/content/docs/, and its images moved from public/img/classic/ to classic/public/img/. starlight-links-validator hard-codes <srcDir>/content/docs, so leaving the pages in place would have made it resolve every Classic link against the old /classic/... URLs.
  • Classic pages are served from the site root (/classic/how-tos/nebari-aws/ becomes classic.nebari.dev/how-tos/nebari-aws/). The site root 302s to /welcome/.
  • New scripts: dev:classic, build:classic, preview:classic, deploy:classic.

Redirects (#733 step 3, handled in the build)

  • public/_redirects on www.nebari.dev sends /classic and /classic/* to https://classic.nebari.dev/:splat (301, path and query kept). Because this runs in the Worker's _redirects, no zone-level redirect rule is needed.
  • The legacy Docusaurus rules (/docs/faq and similar) now point straight at classic.nebari.dev, so each takes one hop instead of two.

Cross-site links

  • The issue listed five, but there were more: debug-deployment, 404, and 7 community pages link to Classic, and Classic's welcome page links to Community. All of them are absolute URLs now.
  • Absolute https://www.nebari.dev/classic/... links inside Classic pages (RELEASE notes, troubleshooting, and similar pages) are root-relative now, so the links validator checks them. The example nebari-config.yaml in advanced-configuration now points at https://classic.nebari.dev/.

Sidebar and banner

  • The main site only has the Nebari and Community groups. routeData.ts now handles those two sections, and the Classic build doesn't use it.
  • The MarkdownContent override is only registered for the Classic build, so the phase-out notice renders on every Classic page without the classic/ path check. It links to https://www.nebari.dev/docs/introduction/.
  • In the Classic header, Docs and Community link back to www.nebari.dev, and the logo links to /welcome/.
  • classic.nebari.dev is added to the analytics production hosts.

Worker and CI (#732, #733 step 2)

  • wrangler.classic.jsonc defines the nebari-docs-classic Worker, serving dist-classic/, and declares classic.nebari.dev as a custom_domain route. Deploying it creates the DNS record and TLS certificate.
  • docs.yml builds both sites in the test step, uploads a preview version of each Worker on PRs, posts both preview URLs in the sticky comment, and deploys both Workers on main.

Before merging: Cloudflare access (#733 step 1)

  • CLOUDFLARE_API_TOKEN needs to be able to create and deploy a second Worker (nebari-docs-classic). If its scope only covers nebari-docs, this PR's preview job will fail at the Classic upload step.
  • Attaching the custom domain also needs Zone › DNS: Edit and Zone › Workers Routes: Edit on nebari.dev. If we'd rather not grant those, drop routes from wrangler.classic.jsonc and have someone add the domain in the dashboard.
  • As with the main Worker, the first CI run seeds the new Worker with a one-time wrangler deploy. Because of the custom_domain route, that first run from this PR also brings classic.nebari.dev live, with the same content it will have after merge.

Test plan

  • bun test test builds both sites. It covers: every page renders with its title, every internal href and image resolves on both sites, the search UI mounts, the main site contains no Classic pages, Classic pages sit at the root with the phase-out notice, no page links to /classic/ on www.nebari.dev, and both _redirects files point at built pages (15 pass)
  • Links validator passes for both builds
  • wrangler dev locally: /classic, /classic/how-tos/nebari-aws/, and /classic/...?x=1 on the main Worker return 301 to the matching path on classic.nebari.dev, and /docs/faq goes straight to classic.nebari.dev/faq/. On the Classic Worker, / returns 302 to /welcome/, pages and images return 200, and unknown paths return 404
  • Preview URLs for both Workers in the PR comment (needs the token scope above)
  • After merge: https://classic.nebari.dev serves over valid TLS, and https://www.nebari.dev/classic/<path> returns 301

🤖 Generated with Claude Code

Build the Classic docs as their own site from the same Astro project.
`DOCS_SITE=classic` switches astro.config.mjs to `docs/classic/` for
content and public assets, outputs to `dist-classic/`, and deploys to a
new `nebari-docs-classic` Worker that attaches classic.nebari.dev as a
custom domain.

- Classic pages are served from the site root; internal links and image
  paths drop the `/classic` prefix
- www.nebari.dev redirects `/classic/*` to classic.nebari.dev with the
  path preserved, and legacy Docusaurus URLs now point there directly
- Cross-site links between the two sites are absolute
- The main site drops the Classic sidebar group; the phase-out banner
  now renders on every Classic page and links to www.nebari.dev
- CI builds, tests, previews, and deploys both Workers
- Tests cover both sites, stale `/classic/` links, and both
  `_redirects` files

Closes #731, closes #732, closes #733

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Docs preview for 731-classic-subdomain:

@jbouder
jbouder merged commit eb6b48f into main Sep 25, 2026
2 of 3 checks passed
@jbouder
jbouder deleted the 731-classic-subdomain branch September 25, 2026 09:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants