feat(site): add pre-release docs banner on main.videojs.org (#1575)

site/CLAUDE.md

@@ -15,7 +15,7 @@ The site deploys via Netlify from two branches:
 | Branch | Deploys to | Content |
 | --- | --- | --- |
 | `site/v10` (production) | **videojs.org** | Stable docs matching the latest release |
-| `main` (branch deploy) | **next.videojs.org** | Pre-release docs (may include unreleased APIs) |
+| `main` (branch deploy) | **main.videojs.org** | Pre-release docs (may include unreleased APIs) |
 
 **On release:** The CD workflow (`.github/workflows/cd.yml`) publishes packages to npm, then force-pushes `main`'s HEAD to `site/v10`. This keeps the production docs in sync with the latest release.
 
@@ -29,7 +29,7 @@ git push origin site/v10
 
 The next release force-pushes `main` to `site/v10`, which already includes the cherry-picked commit (since it originated on `main`). All fixes must land on `main` first — the `site/v10` branch has branch protection that restricts direct pushes to the CD bot.
 
-**Branch deploys (next.videojs.org)** serve `X-Robots-Tag: noindex` headers to prevent search engines from indexing pre-release docs.
+**Branch deploys (main.videojs.org)** serve `X-Robots-Tag: noindex` headers to prevent search engines from indexing pre-release docs. They also render a top banner (`src/components/PrereleaseBanner.astro`) that links back to the stable site. The banner is gated by `isPrereleaseSite(Astro.site)` from `src/consts.ts` — change `PRERELEASE_URL` there if the pre-release hostname moves.
 
 ## Commands
 

site/README.md

@@ -73,7 +73,7 @@ The site deploys via Netlify from two branches:
 | Branch | Deploys to | Content |
 | :--- | :--- | :--- |
 | `site/v10` | **videojs.org** | Stable docs matching the latest release |
-| `main` | **next.videojs.org** | Pre-release docs (may include unreleased APIs) |
+| `main` | **main.videojs.org** | Pre-release docs (may include unreleased APIs) |
 
 On each release, the CD workflow force-pushes `main` to `site/v10`, keeping production docs in sync with published packages.
 

site/astro.config.mjs

@@ -24,6 +24,7 @@ import tsx from 'shiki/langs/tsx.mjs';
 import yaml from 'shiki/langs/yaml.mjs';
 import svgr from 'vite-plugin-svgr';
 import llmsMarkdown from './integrations/llms-markdown';
+import { PRERELEASE_URL, PRODUCTION_URL } from './src/consts.ts';
 import rehypePrepareCodeBlocks from './src/utils/rehypePrepareCodeBlocks';
 import remarkConditionalHeadings from './src/utils/remarkConditionalHeadings';
 import { remarkReadingTime } from './src/utils/remarkReadingTime.mjs';
@@ -32,18 +33,21 @@ import shikiTransformMetadata from './src/utils/shikiTransformMetadata';
 
 // Netlify sets CONTEXT and BRANCH for each deploy. We use them to determine
 // the correct site URL:
-//   - production (site/v10 branch)  → https://videojs.org
-//   - branch-deploy (main branch)   → https://next.videojs.org
+//   - production (site/v10 branch)  → PRODUCTION_URL (videojs.org)
+//   - branch-deploy (main branch)   → PRERELEASE_URL (main.videojs.org)
 //   - deploy-preview (PR branches)  → DEPLOY_PRIME_URL (Netlify subdomain)
 //
+// Hostnames are sourced from src/consts.ts so there is a single place to
+// update if the pre-release or production host ever moves.
+//
 // For URLs that must always point to production regardless of deploy context
 // (e.g. canonical, JSON-LD), use PRODUCTION_URL from src/consts.ts instead.
 const SITE_URL =
   process.env.CONTEXT === 'production'
-    ? 'https://videojs.org'
+    ? PRODUCTION_URL.origin
     : process.env.BRANCH === 'main'
-      ? 'https://next.videojs.org'
-      : process.env.DEPLOY_PRIME_URL || 'https://videojs.org';
+      ? PRERELEASE_URL.origin
+      : process.env.DEPLOY_PRIME_URL || PRODUCTION_URL.origin;
 
 // https://astro.build/config
 export default defineConfig({

site/sentry.server.config.ts

@@ -7,7 +7,7 @@ import * as Sentry from '@sentry/astro';
 // (e.g. a broken PR) out of Sentry — we only want live request failures.
 const isLambdaRuntime = Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME);
 
-// Alert for production (videojs.org) and branch-deploy (next.videojs.org) only.
+// Alert for production (videojs.org) and branch-deploy (main.videojs.org) only.
 // Deploy-preview errors are the PR author's to triage before merge.
 const context = import.meta.env.CONTEXT;
 const isAlertingContext = context === 'production' || context === 'branch-deploy';

site/src/components/PrereleaseBanner.astro

@@ -0,0 +1,32 @@
+---
+import { isPrereleaseSite, PRODUCTION_URL } from '@/consts';
+
+// Only render on the pre-release host. Evaluated at build time, so the markup
+// is omitted entirely from production and deploy-preview builds.
+const showBanner = isPrereleaseSite(Astro.site);
+---
+
+{
+  showBanner && (
+    <div
+      role="region"
+      aria-label="Pre-release documentation notice"
+      class:list={[
+        "py-2 text-p3 md:text-p2",
+        "border-b border-manila-75 bg-manila-50 text-faded-black",
+        "dark:border-soot dark:bg-warm-gray dark:text-manila-light",
+      ]}
+    >
+      <p class="text-center">
+        You&rsquo;re viewing pre-release docs.{" "}
+        <a
+          href={PRODUCTION_URL.href}
+          class="font-bold whitespace-nowrap underline intent:decoration-gold"
+        >
+          Visit videojs.org
+        </a>{" "}
+        for the latest stable version.
+      </p>
+    </div>
+  )
+}

site/src/consts.ts

@@ -2,6 +2,9 @@
 // (e.g. deploy preview URLs), this is stable for canonical URLs and other
 // references that must always point to production.
 export const PRODUCTION_URL = new URL('https://videojs.org');
+// Pre-release docs host (branch deploy of `main`). Keep references centralized
+// here so the hostname can move without touching components.
+export const PRERELEASE_URL = new URL('https://main.videojs.org');
 export const SITE_TITLE = 'Video.js';
 export const SEO_SUFFIX = 'Open Source Video Player';
 export const SITE_DESCRIPTION = `The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.`;
@@ -13,6 +16,10 @@ export const THEME_KEY = 'vjs-site-theme';
 export const BANNER_DISMISS_KEY = 'vjs-legacy-banner-dismissed';
 export const BLOG_PAGE_SIZE = 10;
 
+export function isPrereleaseSite(siteUrl: URL | undefined): boolean {
+  return siteUrl?.origin === PRERELEASE_URL.origin;
+}
+
 /**
  * Video source for demos and examples throughout the site,
  * wherever JS is used. HTML examples use a separate hardcoded source.

site/src/layouts/Base.astro

@@ -10,6 +10,7 @@ import BannerInit from '@/components/BannerInit.astro';
 import { PreferenceSync } from '@/components/docs/PreferenceSync';
 import LegacyBanner from '@/components/LegacyBanner.astro';
 import Posthog from '@/components/Posthog.astro';
+import PrereleaseBanner from '@/components/PrereleaseBanner.astro';
 import ThemeInit from '@/components/ThemeInit.astro';
 
 interface Props {
@@ -172,6 +173,7 @@ const fullTitle =
       </a>
       <PreferenceSync client:idle />
 
+      <PrereleaseBanner />
       <LegacyBanner />
       <slot />
     </div>