move to Page.astro override, enable pagination

Author: KianNH

astro.config.ts

@@ -15,6 +15,7 @@ import rehypeMermaid from "./src/plugins/rehype/mermaid.ts";
 import rehypeAutolinkHeadings from "./src/plugins/rehype/autolink-headings.ts";
 import rehypeExternalLinks from "./src/plugins/rehype/external-links.ts";
 import rehypeHeadingSlugs from "./src/plugins/rehype/heading-slugs.ts";
+import { fileURLToPath } from "url";
 
 async function autogenSections() {
 	const sections = (
@@ -88,13 +89,10 @@ export default defineConfig({
 				Footer: "./src/components/overrides/Footer.astro",
 				Head: "./src/components/overrides/Head.astro",
 				Hero: "./src/components/overrides/Hero.astro",
-				LastUpdated: "./src/components/overrides/LastUpdated.astro",
 				MarkdownContent: "./src/components/overrides/MarkdownContent.astro",
 				Sidebar: "./src/components/overrides/Sidebar.astro",
-				PageSidebar: "./src/components/overrides/PageSidebar.astro",
 				PageTitle: "./src/components/overrides/PageTitle.astro",
 				SocialIcons: "./src/components/overrides/SocialIcons.astro",
-				SkipLink: "./src/components/overrides/SkipLink.astro",
 				TableOfContents: "./src/components/overrides/TableOfContents.astro",
 			},
 			sidebar,
@@ -162,4 +160,16 @@ export default defineConfig({
 		}),
 		react(),
 	],
+	vite: {
+		resolve: {
+			alias: {
+				"./Page.astro": fileURLToPath(
+					new URL("./src/components/overrides/Page.astro", import.meta.url),
+				),
+				"../components/Page.astro": fileURLToPath(
+					new URL("./src/components/overrides/Page.astro", import.meta.url),
+				),
+			},
+		},
+	},
 });

src/components/overrides/Head.astro

@@ -5,7 +5,6 @@ import { differenceInCalendarDays } from "date-fns";
 import "tippy.js/dist/tippy.css";
 
 import { getEntry } from "astro:content";
-import { getPageDescription } from "~/util/description";
 
 const currentSection = Astro.url.pathname.split("/")[1];
 
@@ -139,13 +138,7 @@ if (currentSection) {
 	}
 }
 
-Astro.props.entry.data.description = await getPageDescription(
-	Astro.props.entry,
-	Astro.locals,
-);
-
 // Adding metadata used for reporting and search indexing
-
 // content type
 if (Astro.props.entry.data.pcx_content_type) {
 	const contentType = Astro.props.entry.data.pcx_content_type;

src/components/overrides/LastUpdated.astro

@@ -0,0 +1,64 @@
+---
+import type { Props } from "@astrojs/starlight/props";
+import Default from "@astrojs/starlight/components/Page.astro";
+
+import { generateDescription, generateTableOfContents } from "~/util/props";
+import { getSidebar, flattenSidebar, type SidebarEntry } from "~/util/sidebar";
+
+type Group = Extract<Props["sidebar"][0], { type: "group" }>;
+
+const props = Astro.props;
+const data = props.entry.data;
+
+const html = await Astro.slots.render("default");
+
+if (props.toc) {
+	props.toc.items = await generateTableOfContents(html);
+}
+
+if (props.hasSidebar) {
+	(props.sidebar as unknown as Group) = await getSidebar(Astro);
+
+	if (props.pagination) {
+		const flattened = flattenSidebar(
+			props.sidebar.entries as unknown as SidebarEntry[],
+		);
+
+		const idx = flattened.findIndex((entry) => entry.isCurrent);
+
+		let prev = flattened[idx - 1];
+		let next = flattened[idx + 1];
+
+		if (prev?.attrs["data-group-label"]) {
+			prev = {
+				...prev,
+				label: prev.attrs["data-group-label"],
+			};
+		}
+
+		if (next?.attrs["data-group-label"]) {
+			next = {
+				...next,
+				label: next.attrs["data-group-label"],
+			};
+		}
+
+		props.pagination.prev = prev;
+		props.pagination.next = next;
+	}
+}
+
+if (data.description) {
+	data.description = await generateDescription({
+		markdown: data.description,
+	});
+} else {
+	data.description = await generateDescription({ html });
+}
+
+if (data.updated) {
+	data.lastUpdated = undefined;
+}
+---
+
+<Default {...Astro.props} set:html={html} />

src/components/overrides/Page.astro

@@ -3,12 +3,9 @@ import type { Props } from "@astrojs/starlight/props";
 import Default from "@astrojs/starlight/components/Sidebar.astro";
 
 import { Icon as AstroIcon } from "astro-icon/components";
-
-import { getSidebar, lookupProductTitle } from "~/util/sidebar";
+import { lookupProductTitle } from "~/util/sidebar";
 
 const [product, module] = Astro.url.pathname.split("/").slice(1, -1);
-
-const sidebar = await getSidebar(Astro);
 ---
 
 <a
@@ -26,7 +23,9 @@ const sidebar = await getSidebar(Astro);
 	</span>
 </a>
 <!-- @ts-expect-error sidebar props don't match as we add additional things -->
-<Default {...Astro.props} sidebar={sidebar.entries}><slot /></Default>
+<Default {...Astro.props} sidebar={Astro.props.sidebar.entries}
+	><slot /></Default
+>
 
 <style is:global>
 	:root {

src/components/overrides/PageSidebar.astro

@@ -0,0 +1,88 @@
+import type { Props } from "@astrojs/starlight/props";
+import { parse } from "node-html-parser";
+import he from "he";
+import { remark } from "remark";
+import strip from "strip-markdown";
+import { rehypeExternalLinksOptions } from "~/plugins/rehype/external-links";
+
+export async function generateTableOfContents(
+	html: string,
+): Promise<NonNullable<Props["toc"]>["items"]> {
+	const items = [
+		{
+			text: "Overview",
+			slug: "_top",
+			depth: 1,
+			children: [],
+		},
+	];
+
+	const dom = parse(html);
+	const headers = dom.querySelectorAll("h2[id],h3[id]");
+
+	if (headers) {
+		function headerDepth(header: any) {
+			return Number(header.rawTagName.slice(1));
+		}
+
+		for (const header of headers) {
+			if (header.id === "footnote-label") continue;
+
+			const depth = headerDepth(header);
+
+			const title = he.decode(header.innerText);
+
+			if (depth === 2) {
+				items.push({
+					text: title,
+					slug: header.id,
+					depth,
+					children: [],
+				});
+
+				continue;
+			}
+
+			items.at(-1)?.children.push({
+				text: title,
+				slug: header.id,
+				depth,
+				children: [],
+			});
+		}
+	}
+
+	return items;
+}
+
+/**
+ * Generates a plain-text description for use in the `description` and `og:description` meta tags.
+ *
+ * 1. If there is a `description` property in the frontmatter, strip any Markdown tokens and return.
+ * 2. If there is a `<p>...</p>` element in the HTML, decode any HTML entities and return that.
+ * 3. Return `undefined` to signal to consumers there is no suitable description.
+ */
+export async function generateDescription({
+	html,
+	markdown,
+}: {
+	html?: string;
+	markdown?: string;
+}) {
+	let description = undefined;
+
+	if (markdown) {
+		const file = await remark().use(strip).process(markdown);
+
+		description = file.toString();
+	} else if (html) {
+		const dom = parse(html);
+		const paragraph = dom.querySelector(":root > p");
+
+		if (paragraph) description = he.decode(paragraph.innerText);
+	}
+
+	return description
+		?.replaceAll(rehypeExternalLinksOptions.content.value, "")
+		.trim();
+}