[Docs Site] Add preview_image property to frontmatter for custom images (#20319)

* [Docs Site] Add cover property to frontmatter for custom images

* Use Astro.url for base, add to changelog schema

* Support changelog entries

* changelog default image

* Remove example that doesn't make sense

* fix type import

* move to new file

* Add test image to R2 entry

* Update property name

* Add style guide entry

---------

Co-authored-by: Kody Jackson <[email protected]>

Author: KianNH

src/components/overrides/Head.astro

@@ -5,40 +5,41 @@ import { differenceInCalendarDays } from "date-fns";
 import "tippy.js/dist/tippy.css";
 
 import { getEntry } from "astro:content";
+import { getOgImage } from "~/util/og";
+import type { CollectionEntry } from "astro:content";
 
 // grab the current top-level folder. Remove . characters for 1.1.1.1 URL
 const currentSection = Astro.url.pathname.split("/")[1].replaceAll(".", "");
+const head = Astro.props.entry.data.head;
 
 if (currentSection) {
 	const product = await getEntry("products", currentSection);
 
 	if (product) {
 		if (product.data.meta.title) {
-			const titleIdx = Astro.props.entry.data.head.findIndex(
-				(x) => x.tag === "title",
-			);
+			const titleIdx = head.findIndex((x) => x.tag === "title");
 
 			let title: string;
 
 			if (titleIdx !== -1) {
-				const existingTitle = Astro.props.entry.data.head[titleIdx].content;
+				const existingTitle = head[titleIdx].content;
 				title = `${existingTitle} · ${product.data.meta.title}`;
 
-				Astro.props.entry.data.head[titleIdx] = {
+				head[titleIdx] = {
 					tag: "title",
 					attrs: {},
 					content: title,
 				};
 			} else {
 				title = `${Astro.props.entry.data.title} · ${product.data.meta.title}`;
-				Astro.props.entry.data.head.push({
+				head.push({
 					tag: "title",
 					attrs: {},
 					content: title,
 				});
 			}
 
-			Astro.props.entry.data.head.push({
+			head.push({
 				tag: "meta",
 				attrs: { property: "og:title", content: title },
 				content: "",
@@ -47,15 +48,15 @@ if (currentSection) {
 
 		if (product.data.product.title) {
 			const productName = product.data.product.title;
-			Astro.props.entry.data.head.push({
+			head.push({
 				tag: "meta",
 				attrs: {
 					name: "pcx_product",
 					content: productName,
 				},
 				content: "",
 			});
-			Astro.props.entry.data.head.push({
+			head.push({
 				tag: "meta",
 				attrs: {
 					name: "algolia_product_filter",
@@ -66,58 +67,7 @@ if (currentSection) {
 		}
 
 		if (product.data.product.group) {
-			const group = product.data.product.group.toLowerCase();
-
-			let ogImage = "https://developers.cloudflare.com/cf-twitter-card.png";
-
-			const images: Record<string, string> = {
-				"cloudflare essentials":
-					"https://developers.cloudflare.com/core-services-preview.png",
-				"cloudflare one": "https://developers.cloudflare.com/zt-preview.png",
-				"developer platform":
-					"https://developers.cloudflare.com/dev-products-preview.png",
-				"network security":
-					"https://developers.cloudflare.com/core-services-preview.png",
-				"application performance":
-					"https://developers.cloudflare.com/core-services-preview.png",
-				"application security":
-					"https://developers.cloudflare.com/core-services-preview.png",
-			};
-
-			if (images[group]) {
-				ogImage = images[group];
-			}
-
-			const tags = [
-				{
-					tag: "meta",
-					attrs: {
-						name: "image",
-						content: ogImage,
-					},
-					content: "",
-				},
-				{
-					tag: "meta",
-					attrs: {
-						name: "og:image",
-						content: ogImage,
-					},
-					content: "",
-				},
-				{
-					tag: "meta",
-					attrs: {
-						name: "twitter:image",
-						content: ogImage,
-					},
-					content: "",
-				},
-			] as const;
-
-			Astro.props.entry.data.head.push(...tags);
-
-			Astro.props.entry.data.head.push({
+			head.push({
 				tag: "meta",
 				attrs: {
 					name: "pcx_content_group",
@@ -129,7 +79,7 @@ if (currentSection) {
 	}
 
 	if (currentSection === "style-guide") {
-		Astro.props.entry.data.head.push({
+		head.push({
 			tag: "meta",
 			attrs: {
 				name: "robots",
@@ -138,46 +88,12 @@ if (currentSection) {
 			content: "",
 		});
 	}
-
-	if (currentSection === "changelog") {
-		let changelogImage =
-			"https://developers.cloudflare.com/changelog-preview.png";
-
-		const tags = [
-			{
-				tag: "meta",
-				attrs: {
-					name: "image",
-					content: changelogImage,
-				},
-				content: "",
-			},
-			{
-				tag: "meta",
-				attrs: {
-					name: "og:image",
-					content: changelogImage,
-				},
-				content: "",
-			},
-			{
-				tag: "meta",
-				attrs: {
-					name: "twitter:image",
-					content: changelogImage,
-				},
-				content: "",
-			},
-		] as const;
-
-		Astro.props.entry.data.head.push(...tags);
-	}
 }
 
 // Add noindex tag if present in frontmatter
 
 if (Astro.props.entry.data.noindex) {
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "robots",
@@ -191,15 +107,15 @@ if (Astro.props.entry.data.noindex) {
 // content type
 if (Astro.props.entry.data.pcx_content_type) {
 	const contentType = Astro.props.entry.data.pcx_content_type;
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "pcx_content_type",
 			content: contentType,
 		},
 		content: "",
 	});
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "algolia_content_type",
@@ -212,7 +128,7 @@ if (Astro.props.entry.data.pcx_content_type) {
 // other products
 if (Astro.props.entry.data.products) {
 	const additionalProducts = Astro.props.entry.data.products;
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "pcx_additional_products",
@@ -225,7 +141,7 @@ if (Astro.props.entry.data.products) {
 // other products
 if (Astro.props.entry.data.tags) {
 	const pageTags = Astro.props.entry.data.tags;
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "pcx_tags",
@@ -240,7 +156,7 @@ if (Astro.props.entry.data.updated) {
 		new Date(),
 		Astro.props.entry.data.updated,
 	);
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			name: "pcx_last_reviewed",
@@ -256,7 +172,7 @@ if (Astro.props.entry.data.pcx_content_type === "changelog") {
 	const href = new URL(Astro.site ?? "");
 	href.pathname = Astro.props.entry.slug.concat("/index.xml");
 
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "link",
 		attrs: {
 			rel: "alternate",
@@ -268,15 +184,15 @@ if (Astro.props.entry.data.pcx_content_type === "changelog") {
 }
 
 if (Astro.props.entry.data.external_link) {
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			content: "noindex",
 			name: "robots",
 		},
 		content: "",
 	});
-	Astro.props.entry.data.head.push({
+	head.push({
 		tag: "meta",
 		attrs: {
 			content: `0; url=${Astro.props.entry.data.external_link}`,
@@ -285,6 +201,41 @@ if (Astro.props.entry.data.external_link) {
 		content: "",
 	});
 }
+
+const ogImagePath = await getOgImage(
+	(Astro.props.originalEntry as CollectionEntry<"changelog">) ??
+		Astro.props.entry,
+);
+const ogImageUrl = new URL(ogImagePath, Astro.url.origin).toString();
+
+const ogImageTags = [
+	{
+		tag: "meta",
+		attrs: {
+			name: "image",
+			content: ogImageUrl,
+		},
+		content: "",
+	},
+	{
+		tag: "meta",
+		attrs: {
+			name: "og:image",
+			content: ogImageUrl,
+		},
+		content: "",
+	},
+	{
+		tag: "meta",
+		attrs: {
+			name: "twitter:image",
+			content: ogImageUrl,
+		},
+		content: "",
+	},
+] as const;
+
+head.push(...ogImageTags);
 ---
 
 <script src="src/scripts/footnotes.ts"></script>

src/content/docs/style-guide/frontmatter/custom-properties.mdx

@@ -0,0 +1,17 @@
+---
+title: Custom properties
+sidebar:
+  order: 4
+---
+
+import { Type, MetaInfo } from "~/components";
+
+We have added specific custom [frontmatter](/style-guide/frontmatter/) to meet specific needs.
+
+- `difficulty` <Type text="string" /> <MetaInfo text="optional" />: Difficulty is displayed as a column in the [ListTutorials component](/style-guide/components/list-tutorials/).
+- `external_link` <Type text="string" /> <MetaInfo text="optional" />: Path to another page in our docs or elsewhere. Used to add a crosslink entry to the lefthand navigation sidebar.
+- `pcx_content_type` <Type text="string" /> <MetaInfo text="optional" />: The purpose of the page, and defined through specific pages in [Content strategy](/style-guide/documentation-content-strategy/content-types/).
+- `preview_image` <Type text="string" /> <MetaInfo text="optional" />: An `src` path to the image that you want to use as a custom preview image for social sharing.
+- `products` <Type text="Array<String>" /> <MetaInfo text="optional" />: The names of related products, which show on some grids for Examples, [Tutorials](/style-guide/documentation-content-strategy/content-types/tutorial/), and [Reference Architectures](/style-guide/documentation-content-strategy/content-types/reference-architecture/)
+- `tags` <Type text="Array<String>" /> <MetaInfo text="optional" />: A group of related keywords relating to the purpose of the page.
+- `updated` <Type text="Date" /> <MetaInfo text="optional" />: This is used to automatically add the [LastReviewed component](/style-guide/components/last-reviewed/).

src/pages/changelog/[...slug].astro

@@ -36,6 +36,7 @@ const props = {
 	headings,
 	hideTitle: true,
 	hideBreadcrumbs: true,
+	originalEntry: note,
 } as StarlightPageProps;
 ---