feat(website): describe the product on /download, not just on the landing page

/download carried only the site-wide Organization and WebSite pair, so the
one URL we want ranking for "openscreen download" said nothing about the
software it serves.

It now emits a @graph: a WebPage node that is part of the site-wide WebSite
and whose about/mainEntity is the product, plus the SoftwareApplication
itself. Referencing #software without defining it would have left a dangling
pointer with nothing for a crawler to attach to this URL, so the entity is
emitted here too — not duplication, since the shared @id makes both copies
one entity rather than two competing ones. Docs pages still get neither.

The node moves to src/lib/structured-data.ts so the two pages cannot drift,
and the download page's copy carries softwareVersion and datePublished off
the build-time release lookup it already reads. That needs the release date
in schema.org's Date form, hence publishedIso alongside the display string.

Verified against the production build: tsc and biome clean, all four nodes
present in the served DOM with no hydration errors, landing page output
unchanged.

Author: EtienneLescot

website/docusaurus.config.ts

@@ -16,8 +16,9 @@ const SITE_DESCRIPTION =
 
 // Site-wide structured data. Organization + WebSite are true of every page, so
 // they belong here; the SoftwareApplication entity describes the product rather
-// than the site and is emitted on the landing page only (src/pages/index.tsx),
-// because duplicating it under every docs URL is what earns a manual action.
+// than the site and lives in src/lib/structured-data.ts, emitted only by the two
+// pages that are about the product (the landing page and /download), because
+// repeating it under every docs URL is what earns a manual action.
 const ORGANIZATION_LD = {
 	"@context": "https://schema.org",
 	"@type": "Organization",
@@ -121,12 +122,18 @@ async function fetchLatestRelease(): Promise<LatestRelease> {
 		// resolve against the visitor's locale and time zone on hydration and
 		// mismatch the server-rendered string.
 		let published = "";
+		let publishedIso = "";
 		if (typeof data.published_at === "string") {
 			const [y, m, d] = data.published_at.slice(0, 10).split("-");
-			if (y && m && d) published = `${Number(d)} ${MONTHS[Number(m) - 1]} ${y}`;
+			if (y && m && d) {
+				published = `${Number(d)} ${MONTHS[Number(m) - 1]} ${y}`;
+				// Kept alongside the display string for /download's structured
+				// data, which needs schema.org's Date form rather than prose.
+				publishedIso = `${y}-${m}-${d}`;
+			}
 		}
 
-		return { tag: data.tag_name, published, assets };
+		return { tag: data.tag_name, published, publishedIso, assets };
 	} catch {
 		return null;
 	}

website/src/lib/release.ts

@@ -15,6 +15,8 @@ export type LatestRelease = {
 	tag: string;
 	/** Pre-formatted at build time, e.g. "19 July 2026". Empty if unknown. */
 	published: string;
+	/** The same date as YYYY-MM-DD, for structured data. Empty if unknown. */
+	publishedIso: string;
 	assets: ReleaseAsset[];
 } | null;
 

website/src/lib/structured-data.ts

@@ -0,0 +1,80 @@
+/**
+ * Schema.org nodes for the product, shared by the two pages that are genuinely
+ * about it: the landing page and /download.
+ *
+ * The Organization and WebSite pair lives in docusaurus.config.ts instead,
+ * because it is true of every URL and is emitted from headTags. The product
+ * entity deliberately is not: a SoftwareApplication repeated under every docs
+ * page is what earns a manual action. Emitting it on the two pages that
+ * describe the product costs nothing, because both use the same @id — search
+ * engines reconcile them into one entity rather than two competing copies.
+ */
+
+import type { LatestRelease } from "./release";
+
+const SITE_URL = "https://getopenscreen.com";
+
+/** Minted to match the @ids in docusaurus.config.ts; keep the two in step. */
+export const ORGANIZATION_ID = `${SITE_URL}/#organization`;
+export const WEBSITE_ID = `${SITE_URL}/#website`;
+export const SOFTWARE_ID = `${SITE_URL}/#software`;
+
+const SOFTWARE_APPLICATION_LD = {
+	"@type": "SoftwareApplication",
+	"@id": SOFTWARE_ID,
+	name: "OpenScreen",
+	applicationCategory: "MultimediaApplication",
+	applicationSubCategory: "Screen Recorder",
+	operatingSystem: "Windows, macOS, Linux",
+	description:
+		"Free, open-source screen recorder and video editor. Native capture on macOS and Windows, multi-track timeline editing, on-device Whisper captions, and MP4/GIF export — no watermarks, no subscription, no account.",
+	url: SITE_URL,
+	// Our own page rather than the Releases list: it is the URL we want ranking
+	// for "openscreen download", and it routes to GitHub from there anyway.
+	downloadUrl: `${SITE_URL}/download/`,
+	installUrl: "https://github.com/getopenscreen/openscreen/releases",
+	softwareHelp: `${SITE_URL}/docs/intro/`,
+	license: "https://github.com/getopenscreen/openscreen/blob/main/LICENSE",
+	isAccessibleForFree: true,
+	// `offers` at price 0 is what lets a result carry a "Free" annotation;
+	// omitting it on a free app just forfeits the label.
+	offers: {
+		"@type": "Offer",
+		price: "0",
+		priceCurrency: "USD",
+	},
+	featureList: [
+		"Native screen capture (ScreenCaptureKit, Windows Graphics Capture)",
+		"Multi-track timeline editing with zoom, trim, and speed regions",
+		"On-device Whisper transcription and burned-in captions",
+		"Webcam picture-in-picture and cursor smoothing",
+		"MP4 (H.264/H.265) and animated GIF export",
+	],
+	publisher: { "@id": ORGANIZATION_ID },
+};
+
+/**
+ * The product entity, carrying the version and release date wherever the caller
+ * has the build-time release lookup to hand. Those two properties belong to the
+ * same @id as the bare node, so a page that knows the current version and one
+ * that doesn't describe one entity, not a contradiction.
+ */
+export function softwareApplicationLd(release?: LatestRelease) {
+	if (!release) return SOFTWARE_APPLICATION_LD;
+	return {
+		...SOFTWARE_APPLICATION_LD,
+		// Tags are minted as v1.8.0; schema.org wants the version alone.
+		softwareVersion: release.tag.replace(/^v/, ""),
+		...(release.publishedIso ? { datePublished: release.publishedIso } : {}),
+	};
+}
+
+/**
+ * Serializes nodes under the document-level @context. Several nodes become an
+ * @graph rather than one <script> apiece, so cross-references between them
+ * resolve within a single document.
+ */
+export function jsonLd(...nodes: object[]): string {
+	const body = nodes.length === 1 ? nodes[0] : { "@graph": nodes };
+	return JSON.stringify({ "@context": "https://schema.org", ...body });
+}

website/src/pages/download.tsx

@@ -1,3 +1,4 @@
+import Head from "@docusaurus/Head";
 import Link from "@docusaurus/Link";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import Heading from "@theme/Heading";
@@ -12,11 +13,19 @@ import {
 } from "lucide-react";
 
 import { type AssetKind, findAsset, formatSize, type LatestRelease } from "../lib/release";
+import { jsonLd, SOFTWARE_ID, softwareApplicationLd, WEBSITE_ID } from "../lib/structured-data";
 import styles from "./download.module.css";
 
 const REPO_URL = "https://github.com/getopenscreen/openscreen";
 const RELEASES_URL = `${REPO_URL}/releases`;
 const LATEST_URL = `${RELEASES_URL}/latest`;
+const PAGE_URL = "https://getopenscreen.com/download/";
+
+// Shared by <Layout> and the WebPage node below so the two cannot drift: a
+// structured-data description that contradicts the meta one is worse than none.
+const PAGE_TITLE = "Download for Windows, macOS & Linux";
+const PAGE_DESCRIPTION =
+	"Download OpenScreen free for Windows, macOS, and Linux — .dmg, .exe, .deb, .pacman, AppImage, and a Nix flake. Open source, no account, no watermark.";
 
 type PlatformSpec = {
 	id: string;
@@ -58,15 +67,40 @@ const PLATFORMS: PlatformSpec[] = [
 	},
 ];
 
+/**
+ * Hooks this URL onto the site's entity graph: a WebPage node that is part of
+ * the site-wide WebSite and whose subject is the product entity, plus that
+ * entity itself under its canonical @id. Emitting the SoftwareApplication here
+ * as well as on the landing page is not duplication — the shared @id makes both
+ * copies one entity — and it is what lets this page, the one we want ranking for
+ * "openscreen download", carry the app's category, platforms, price, and version.
+ */
+function downloadPageLd(release: LatestRelease): string {
+	return jsonLd(
+		{
+			"@type": "WebPage",
+			"@id": `${PAGE_URL}#webpage`,
+			url: PAGE_URL,
+			name: PAGE_TITLE,
+			description: PAGE_DESCRIPTION,
+			inLanguage: "en",
+			isPartOf: { "@id": WEBSITE_ID },
+			about: { "@id": SOFTWARE_ID },
+			mainEntity: { "@id": SOFTWARE_ID },
+		},
+		softwareApplicationLd(release),
+	);
+}
+
 export default function DownloadPage() {
 	const { siteConfig } = useDocusaurusContext();
 	const release = (siteConfig.customFields?.latestRelease ?? null) as LatestRelease;
 
 	return (
-		<Layout
-			title="Download for Windows, macOS & Linux"
-			description="Download OpenScreen free for Windows, macOS, and Linux — .dmg, .exe, .deb, .pacman, AppImage, and a Nix flake. Open source, no account, no watermark."
-		>
+		<Layout title={PAGE_TITLE} description={PAGE_DESCRIPTION}>
+			<Head>
+				<script type="application/ld+json">{downloadPageLd(release)}</script>
+			</Head>
 			<header className={styles.hero}>
 				<div className={styles.heroInner}>
 					<span className={styles.badge}>

website/src/pages/index.tsx

@@ -17,6 +17,7 @@ import {
 	TerminalSquare,
 } from "lucide-react";
 
+import { jsonLd, softwareApplicationLd } from "../lib/structured-data";
 import styles from "./index.module.css";
 
 // Static decorative waveform bars for the "multi-track editor" bento card —
@@ -25,50 +26,16 @@ import styles from "./index.module.css";
 const MINI_WAVEFORM_A = [30, 55, 80, 45, 65, 90, 50, 35, 70, 60, 40, 75, 55, 30];
 const MINI_WAVEFORM_B = [45, 65, 35, 85, 55, 40, 70, 90, 50, 30, 60, 75, 45, 65, 35, 55];
 
-// The product entity, distinct from the Organization/WebSite pair in
-// docusaurus.config.ts. `offers` at price 0 is what lets a result carry a
-// "Free" annotation; omitting it on a free app just forfeits the label.
-const SOFTWARE_APPLICATION_LD = {
-	"@context": "https://schema.org",
-	"@type": "SoftwareApplication",
-	"@id": "https://getopenscreen.com/#software",
-	name: "OpenScreen",
-	applicationCategory: "MultimediaApplication",
-	applicationSubCategory: "Screen Recorder",
-	operatingSystem: "Windows, macOS, Linux",
-	description:
-		"Free, open-source screen recorder and video editor. Native capture on macOS and Windows, multi-track timeline editing, on-device Whisper captions, and MP4/GIF export — no watermarks, no subscription, no account.",
-	url: "https://getopenscreen.com",
-	// Our own page rather than the Releases list: it is the URL we want ranking
-	// for "openscreen download", and it routes to GitHub from there anyway.
-	downloadUrl: "https://getopenscreen.com/download/",
-	installUrl: "https://github.com/getopenscreen/openscreen/releases",
-	softwareHelp: "https://getopenscreen.com/docs/intro/",
-	license: "https://github.com/getopenscreen/openscreen/blob/main/LICENSE",
-	isAccessibleForFree: true,
-	offers: {
-		"@type": "Offer",
-		price: "0",
-		priceCurrency: "USD",
-	},
-	featureList: [
-		"Native screen capture (ScreenCaptureKit, Windows Graphics Capture)",
-		"Multi-track timeline editing with zoom, trim, and speed regions",
-		"On-device Whisper transcription and burned-in captions",
-		"Webcam picture-in-picture and cursor smoothing",
-		"MP4 (H.264/H.265) and animated GIF export",
-	],
-	publisher: { "@id": "https://getopenscreen.com/#organization" },
-};
-
 export default function Home() {
 	return (
 		<Layout
 			title="Free open-source screen recorder & video editor"
 			description="OpenScreen is a free, open-source screen recorder and video editor for Windows, macOS, and Linux — native capture, on-device captions, no watermarks."
 		>
 			<Head>
-				<script type="application/ld+json">{JSON.stringify(SOFTWARE_APPLICATION_LD)}</script>
+				{/* The product entity, distinct from the Organization/WebSite pair
+				    emitted site-wide from docusaurus.config.ts. */}
+				<script type="application/ld+json">{jsonLd(softwareApplicationLd())}</script>
 			</Head>
 			<header className={styles.hero}>
 				<div className={styles.heroInner}>