feat(site): framework-specific SEO metadata for docs (#541)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

site/src/consts.ts

@@ -1,5 +1,6 @@
-export const SITE_TITLE = 'Video.js 10';
-export const SITE_DESCRIPTION = `For over 15 years, Video.js has been the world's web video player. Now rebuilt in v10 for modern development and performance.`;
+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.`;
 export const GITHUB_REPO_URL = 'https://github.com/videojs/v10/';
 export const DISCORD_INVITE_URL = 'https://discord.gg/JBqHh485uF';
 export const THEME_KEY = 'vjs-site-theme';

site/src/content/docs/concepts/architecture.mdx

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-description: Understanding the three-tier architecture of Video.js v10 - State, UI, and Renderers
+description: How Video.js structures its video player — state management, UI components, and platform renderers
 ---
 
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';

site/src/content/docs/concepts/skins.mdx

@@ -1,6 +1,6 @@
 ---
 title: Skins
-description: Understanding skins in Video.js v10 - packaged sets of UI components and styles
+description: Packaged sets of video player UI components and styles that you can customize or replace
 ---
 
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';

site/src/content/docs/concepts/ui-components.mdx

@@ -1,6 +1,6 @@
 ---
 title: UI components
-description: Understanding Video.js v10's primitive-based component architecture
+description: Primitive-based component architecture for building accessible, composable video player controls
 ---
 
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';

site/src/content/docs/how-to/installation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Installation
-description: Get started quickly with Video.js by building your first embed code
+description: Install Video.js and build your first player with streaming support and accessible controls
 ---
 
 import JSPicker from '@/components/installation/JSPicker.astro';
@@ -21,7 +21,13 @@ import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs.tsx';
 Video.js v10 is currently in _beta_. The API may evolve with [feedback&#x1F64F;](https://github.com/videojs/v10/issues). See the [Changelog](https://github.com/videojs/v10/blob/main/CHANGELOG.md)\[todo\] for recent updates and the <DocsLink slug="concepts/v10-roadmap">Roadmap</DocsLink> for more details on what's coming.
 </Aside>
 
-Video.js is **audio and video player components** &mdash; intentionally built to achieve **minimal bundle sizes** while providing **framework-specific customization** and a **great viewer experience**.
+<FrameworkCase frameworks={["react"]}>
+Video.js is a **React video player component library** &mdash; composable primitives, hooks, and TypeScript types for building accessible, customizable players with minimal bundle size.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+Video.js is an **HTML video player built on custom elements** &mdash; lightweight, framework-free components for building accessible, customizable players with minimal bundle size.
+</FrameworkCase>
+
 Answer the questions below to get started quickly with your first embed code.
 
 ## Choose your JS framework

site/src/content/docs/reference/buffering-indicator.mdx

@@ -2,7 +2,7 @@
 title: BufferingIndicator
 frameworkTitle:
   html: media-buffering-indicator
-description: A component that displays a loading indicator when media is buffering
+description: Loading indicator that displays when the video player is buffering or waiting for data
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/controls.mdx

@@ -2,7 +2,7 @@
 title: Controls
 frameworkTitle:
   html: media-controls
-description: Containers for composing and auto-hiding player controls
+description: Container component for composing and auto-hiding video player controls on user interaction
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/fullscreen-button.mdx

@@ -2,7 +2,7 @@
 title: FullscreenButton
 frameworkTitle:
   html: media-fullscreen-button
-description: A button component for entering and exiting fullscreen mode
+description: Accessible fullscreen toggle button with keyboard support and state reflection
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/mute-button.mdx

@@ -2,7 +2,7 @@
 title: MuteButton
 frameworkTitle:
   html: media-mute-button
-description: A button component for muting and unmuting audio playback
+description: Accessible mute/unmute button with keyboard support and volume state reflection
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/pip-button.mdx

@@ -2,7 +2,7 @@
 title: PiPButton
 frameworkTitle:
   html: media-pip-button
-description: A button component for entering and exiting picture-in-picture mode
+description: Accessible picture-in-picture toggle button with keyboard support and state reflection
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/play-button.mdx

@@ -2,7 +2,7 @@
 title: PlayButton
 frameworkTitle:
   html: media-play-button
-description: A button component for playing and pausing media playback
+description: Accessible play/pause button with keyboard support and customizable rendering
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/poster.mdx

@@ -2,7 +2,7 @@
 title: Poster
 frameworkTitle:
   html: media-poster
-description: Poster image component that stays visible until playback starts
+description: Poster image component that displays a thumbnail until video playback starts
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/seek-button.mdx

@@ -2,7 +2,7 @@
 title: SeekButton
 frameworkTitle:
   html: media-seek-button
-description: A button component for seeking media playback forward or backward by a specified number of seconds
+description: Accessible seek button for skipping forward or backward by a configurable number of seconds
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/content/docs/reference/time.mdx

@@ -2,7 +2,7 @@
 title: Time
 frameworkTitle:
   html: media-time
-description: Components for displaying and composing media time information
+description: Time display components for showing current time, duration, and remaining time in a video player
 ---
 
 import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

site/src/layouts/Base.astro

@@ -4,7 +4,7 @@
 import { Font } from 'astro:assets';
 import type { ImageMetadata } from 'astro';
 
-import { SITE_TITLE } from '@/consts';
+import { SEO_SUFFIX, SITE_TITLE } from '@/consts';
 
 import '@/styles/globals.css';
 
@@ -17,17 +17,17 @@ interface Props {
   description: string;
   image?: ImageMetadata;
   canonical?: string;
+  suffix?: string;
 }
-const { canonical } = Astro.props;
+const { canonical, suffix } = Astro.props;
 const canonicalURL = canonical || new URL(Astro.url.pathname, Astro.site);
 
 const { title, description, image } = Astro.props;
 
-const fullTitle = Array.isArray(title)
-  ? `${title.filter((t) => t !== SITE_TITLE).join(' | ')} | ${SITE_TITLE}`
-  : title === SITE_TITLE
-    ? title
-    : `${title} | ${SITE_TITLE}`;
+const seoSuffix = suffix ?? SEO_SUFFIX;
+const pageTitle = Array.isArray(title) ? title.join(' | ') : title;
+const fullTitle =
+  pageTitle === SITE_TITLE ? `${SITE_TITLE} | ${seoSuffix}` : `${pageTitle} | ${SITE_TITLE} | ${seoSuffix}`;
 ---
 
 <html lang="en">

site/src/layouts/Docs.astro

@@ -9,7 +9,7 @@ import FilmGrain from '@/components/FilmGrain';
 import Footer from '@/components/Footer.astro';
 import FooterEasterEgg from '@/components/FooterEasterEgg.astro';
 import NavBar from '@/components/NavBar/NavBar.astro';
-import type { SupportedFramework } from '@/types/docs';
+import { FRAMEWORK_LABELS, type SupportedFramework } from '@/types/docs';
 import { getDocTitle } from '@/utils/docs/title';
 import Base from './Base.astro';
 
@@ -25,10 +25,11 @@ const { doc, framework, slug } = Astro.props;
 const allDocs = await getCollection('docs');
 const docTitles = new Map(allDocs.map((d) => [d.id, getDocTitle(d, framework)]));
 
+const seoCategory = `${FRAMEWORK_LABELS[framework]} Video Player`;
 const docsSidebarId = 'docs-sidebar';
 ---
 
-<Base title={[getDocTitle(doc, framework), 'Docs']} description={doc.data.description}>
+<Base title={getDocTitle(doc, framework)} suffix={`Open Source ${FRAMEWORK_LABELS[framework]} Video Player`} description={`${doc.data.description} — Video.js ${seoCategory}.`}>
   <Fragment slot="priority-head">
     <StyleInit />
   </Fragment>

site/src/pages/blog/[...page].astro

@@ -44,12 +44,12 @@ const jsonLdSchema = createBlogCollectionSchema({
 });
 ---
 
-<Blog title="Blog" description="Articles, announcements, news, updates, and more">
+<Blog title="Blog" description="News and updates from the Video.js open-source video player project">
   <JsonLd slot="head" schema={jsonLdSchema} />
   <header class="mb-10 md:mb-20 w-full max-w-3xl mx-auto">
     <h1 class="text-h4 md:text-h2 mb-2">Video.js Blog</h1>
     <p class="text-lg font-medium md:text-h5 text-dark-40 dark:text-light-40">
-      {page.data.length === 0 ? 'Coming soon' : 'Articles, announcements, news, updates, and more'}
+      {page.data.length === 0 ? 'Coming soon' : 'News and updates from the Video.js open-source video player project'}
     </p>
   </header>
   <div class="grid gap-10 w-full max-w-3xl mx-auto">

site/src/pages/index.astro

@@ -25,8 +25,8 @@ const poster = `${VJS8_DEMO_VIDEO.poster}?time=0`;
       >
         <h1 class="text-h4 md:text-h1 text-balance lg:text-pretty">The Open Source Player for the Web</h1>
         <p class="md:text-lg text-balance max-w-100">
-          For over 15 years, Video.js has been the world’s web video player. Now rebuilt in v10 for modern development
-          and performance.
+          The open-source video player for React and HTML. Lightweight, accessible components built for performance and
+          streaming.
         </p>
       </div>
       <div class="vjs relative z-10 w-full -mb-11 md:-mb-21 lg:-mb-32 grid grid-cols-1 grid-rows-1">

site/src/utils/jsonLd/schemas.ts

@@ -30,6 +30,12 @@ export function createTechArticleSchema(params: {
     ...(params.wordCount && { wordCount: params.wordCount }),
     ...(params.readingTime && { timeRequired: `PT${params.readingTime}M` }),
     ...(params.articleSection && { articleSection: params.articleSection }),
+    about: {
+      '@type': 'SoftwareApplication',
+      name: 'Video.js',
+      applicationCategory: 'MultimediaApplication',
+      operatingSystem: 'Web',
+    },
     author: {
       '@type': 'Organization',
       name: 'Video.js',
@@ -112,7 +118,7 @@ export function createBlogCollectionSchema(params: {
     '@context': 'https://schema.org',
     '@type': 'CollectionPage',
     name: 'Video.js Blog',
-    description: 'Articles, announcements, news, updates, and more',
+    description: 'News and updates from the Video.js open-source video player project',
     url: params.url,
     mainEntity: {
       '@type': 'ItemList',