@nu-appdev/northwestern-starlight-theme 1.3.2 → 1.5.0

package/src/config-schema.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+
+/**
+ * Non-empty string helper used when reading titles from mixed Starlight config shapes.
+ *
+ * Trims surrounding whitespace and rejects empty strings after trimming.
+ */
+export const nonEmptyStringSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .meta({ description: "A non-empty string with surrounding whitespace removed." });
+
+/**
+ * CSS pixel length helper used for hero image sizing.
+ *
+ * Restricts values to explicit pixel lengths so consumers get deterministic
+ * hero sizing and friendly validation errors for malformed values.
+ */
+const pixelLengthSchema = z
+    .string()
+    .trim()
+    .regex(/^\d+px$/, 'Expected a pixel value like "500px".')
+    .meta({
+        description: 'A CSS pixel length such as "500px" or "750px".',
+        examples: ["500px", "750px", "1000px"],
+    });
+
+/**
+ * Configuration for the homepage hero section.
+ *
+ * Controls hero layout, title visibility, and image sizing. This is used as
+ * the `homepage` property of the top-level theme config.
+ */
+const northwesternHomepageConfigSchema = z
+    .strictObject({
+        /**
+         * Hero layout style.
+         *
+         * - `"centered"`: image above title, all content centered
+         * - `"split"`: text and actions on the left, image on the right
+         */
+        layout: z.enum(["centered", "split"]).meta({
+            description: 'Hero layout style. Use "centered" for a stacked hero or "split" for a two-column layout.',
+            examples: ["centered", "split"],
+        }),
+
+        /**
+         * Whether to display the page title inside the hero.
+         *
+         * Set this to `false` when the hero image already contains the title
+         * as part of a branded lockup.
+         */
+        showTitle: z.boolean().meta({
+            description: "Whether to render the page title inside the hero section.",
+        }),
+
+        /**
+         * Maximum width of the hero image in the centered layout.
+         *
+         * Use a larger value for wide lockup images that would otherwise feel cramped.
+         */
+        imageWidth: pixelLengthSchema.meta({
+            description: "Maximum width of the hero image in the centered layout, expressed in pixels.",
+            examples: ["500px", "750px"],
+        }),
+    })
+    .partial()
+    .meta({
+        description: "Homepage hero configuration. Controls layout, title visibility, and hero image sizing.",
+    });
+
+/**
+ * Top-level configuration for the Northwestern Starlight theme plugin.
+ *
+ * With `defineNorthwesternConfig`, pass this object as the `theme` key.
+ * With `northwesternTheme()` directly, pass it as the function argument.
+ */
+export const northwesternThemeConfigSchema = z
+    .strictObject({
+        /**
+         * Homepage hero layout configuration.
+         */
+        homepage: northwesternHomepageConfigSchema.optional().meta({
+            description: "Homepage hero configuration.",
+        }),
+
+        /**
+         * Mermaid diagram support.
+         *
+         * - `true`: auto-detect Mermaid packages and enable support when available
+         * - `false`: disable Mermaid integration entirely
+         * - `object`: merge custom Mermaid options with Northwestern defaults
+         */
+        mermaid: z
+            .union([z.boolean(), z.record(z.string(), z.unknown())])
+            .optional()
+            .meta({
+                description:
+                    "Mermaid support toggle or override object. Use true to auto-detect, false to disable, or an object to merge custom Mermaid options.",
+            }),
+
+        /**
+         * Open Graph image generation.
+         *
+         * Generates a branded 1200x630 image for each docs page when `site`
+         * is configured in `astro.config.ts`.
+         */
+        ogImage: z.boolean().optional().meta({
+            description: "Whether to generate branded Open Graph images for docs pages.",
+        }),
+    })
+    .meta({
+        description: "Top-level Northwestern theme plugin configuration.",
+    });
+
+/**
+ * Configuration options for the standalone Northwestern Mermaid integration.
+ *
+ * This intentionally validates only the Northwestern-owned wrapper surface and
+ * allows additional upstream `astro-mermaid` options to pass through unchanged.
+ */
+export const northwesternMermaidOptionsSchema = z
+    .looseObject({
+        /**
+         * Show the hover toolbar on rendered diagrams.
+         *
+         * The toolbar provides fullscreen, download, and copy-source actions.
+         */
+        toolbar: z.boolean().optional().meta({
+            description: "Whether to show the Mermaid hover toolbar with fullscreen, download, and copy actions.",
+        }),
+    })
+    .meta({
+        description:
+            "Northwestern Mermaid integration options. Supports the `toolbar` toggle plus passthrough astro-mermaid options.",
+    });
+
+/**
+ * Configuration options for `defineNorthwesternConfig()`.
+ *
+ * This schema validates the Northwestern-owned wrapper surface while allowing
+ * the rest of Astro's top-level config to pass through untouched.
+ */
+export const northwesternConfigOptionsSchema = z
+    .looseObject({
+        /**
+         * Full Starlight configuration object.
+         *
+         * This is forwarded to `starlight()` after Northwestern defaults and
+         * helper-managed integration ordering are applied.
+         */
+        starlight: z.looseObject({}).meta({
+            description: "Full Starlight configuration object passed through to the Starlight integration.",
+        }),
+
+        /**
+         * Northwestern theme plugin options.
+         */
+        theme: northwesternThemeConfigSchema.optional().meta({
+            description: "Northwestern theme plugin options.",
+        }),
+
+        /**
+         * Mermaid diagram support.
+         *
+         * - `true`: add Northwestern Mermaid with defaults
+         * - `false`: disable Mermaid
+         * - `object`: add Northwestern Mermaid with custom options
+         */
+        mermaid: z.union([z.boolean(), northwesternMermaidOptionsSchema]).optional().meta({
+            description:
+                "Mermaid integration toggle or options object. Use true for defaults, false to disable, or an object for custom Mermaid behavior.",
+        }),
+
+        /**
+         * Additional Starlight plugins to register after the Northwestern theme.
+         */
+        plugins: z.array(z.unknown()).optional().meta({
+            description: "Additional Starlight plugins to append after the Northwestern theme plugin.",
+        }),
+
+        /**
+         * Escape hatch for advanced integration ordering.
+         *
+         * Use `before` for integrations that must run before Mermaid/Starlight,
+         * and `after` for integrations that should be appended after Starlight.
+         */
+        integrations: z
+            .strictObject({
+                /**
+                 * Integrations added before Mermaid and Starlight.
+                 */
+                before: z.array(z.unknown()).optional().meta({
+                    description: "Astro integrations to register before Mermaid and Starlight.",
+                }),
+
+                /**
+                 * Integrations added after Starlight.
+                 */
+                after: z.array(z.unknown()).optional().meta({
+                    description: "Astro integrations to register after Starlight.",
+                }),
+            })
+            .optional()
+            .meta({
+                description: "Advanced integration ordering overrides.",
+            }),
+    })
+    .meta({
+        description: "Options for defineNorthwesternConfig(), combining Astro config with Northwestern-specific keys.",
+    });
+
+function formatIssuePath(path: PropertyKey[]): string {
+    return path.length > 0 ? path.join(".") : "config";
+}
+
+/**
+ * Format Zod validation errors as stable, package-prefixed user-facing messages.
+ *
+ * The goal is to fail fast with errors that point directly at the bad config
+ * path instead of surfacing cryptic downstream behavior.
+ */
+function formatValidationError(scope: string, error: z.ZodError): string {
+    const lines = error.issues.map((issue) => {
+        if (issue.code === "unrecognized_keys") {
+            const basePath = formatIssuePath(issue.path);
+            return issue.keys
+                .map((key) => `${basePath === "config" ? key : `${basePath}.${key}`}: Unrecognized key.`)
+                .join("\n");
+        }
+
+        return `${formatIssuePath(issue.path)}: ${issue.message}`;
+    });
+
+    return [`[northwestern-starlight-theme] Invalid ${scope}.`, ...lines.map((line) => `  - ${line}`)].join("\n");
+}
+
+/**
+ * Validate a public config object and throw a friendly package-scoped error on failure.
+ */
+export function validateSchema<T>(schema: z.ZodType<T>, value: unknown, scope: string): T {
+    const parsed = schema.safeParse(value);
+
+    if (!parsed.success) {
+        throw new Error(formatValidationError(scope, parsed.error));
+    }
+
+    return parsed.data;
+}

package/src/og/endpoint.ts

@@ -0,0 +1,63 @@
+import { getCollection } from "astro:content";
+import config from "virtual:northwestern-theme/config";
+import { renderOGImage } from "./render";
+
+const siteTitle = config.ogImage.siteTitle;
+const logoPath = config.ogImage.logoPath;
+const resvgWasmPath = config.ogImage.resvgWasmPath;
+const docs = await getCollection("docs");
+let changelogs: typeof docs = [];
+try {
+    changelogs = await getCollection("changelogs" as "docs");
+} catch {}
+const pages = Object.fromEntries([...docs, ...changelogs].map((entry) => [entry.id, entry]));
+
+function getImageOptions(path: string, page: (typeof docs)[number]) {
+    const isIndex = path === "index";
+    const isChangelogVersion = path.startsWith("changelog/version/");
+    const title = isIndex ? siteTitle : isChangelogVersion ? `Changelog\n${page.data.title}` : page.data.title;
+    return {
+        resvgWasmPath,
+        title,
+        description: page.data.description,
+        logo: { path: logoPath, size: [80] as [number] },
+        bgGradient: [[64, 31, 104]] as [number, number, number][],
+        padding: [60, 220] as [number, number],
+        border: {
+            color: [164, 149, 195] as [number, number, number],
+            width: 12,
+        },
+        font: {
+            title: {
+                families: ["Poppins"],
+                weight: "Bold" as const,
+                size: isChangelogVersion ? 64 : 56,
+                lineHeight: 1.3,
+                color: [255, 255, 255] as [number, number, number],
+            },
+            description: {
+                families: ["Akkurat Pro"],
+                size: 32,
+                lineHeight: 1.5,
+                color: [182, 172, 209] as [number, number, number],
+            },
+        },
+        fonts: [
+            "https://common.northwestern.edu/v8/css/fonts/Poppins-Bold.woff",
+            "https://common.northwestern.edu/v8/css/fonts/AkkuratProRegular.woff",
+        ],
+    };
+}
+
+export function getStaticPaths() {
+    return Object.entries(pages).map(([pagePath, page]) => ({
+        params: { slug: `${pagePath}.png` },
+        props: { imageOptions: getImageOptions(pagePath, page) },
+    }));
+}
+
+export async function GET({ props }: { props: { imageOptions: ReturnType<typeof getImageOptions> } }) {
+    return new Response(await renderOGImage(props.imageOptions), {
+        headers: { "Content-Type": "image/png" },
+    });
+}

package/src/og/render.ts

@@ -0,0 +1,260 @@
+import fs from "node:fs/promises";
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+import satori from "satori";
+
+type RGBColor = [r: number, g: number, b: number];
+type FontWeight = string;
+
+interface FontConfig {
+    color?: RGBColor;
+    size?: number;
+    weight?: FontWeight;
+    lineHeight?: number;
+    families?: string[];
+}
+
+interface OGImageOptions {
+    resvgWasmPath: string;
+    title: string;
+    description?: string;
+    logo?: {
+        path: string;
+        size?: [width?: number, height?: number];
+    };
+    bgGradient?: RGBColor[];
+    border?: {
+        color?: RGBColor;
+        width?: number;
+    };
+    padding?: number | [vertical: number, horizontal: number];
+    font?: {
+        title?: FontConfig;
+        description?: FontConfig;
+    };
+    fonts?: string[];
+}
+
+const [width, height] = [1200, 630];
+
+let wasmInitialized = false;
+async function ensureWasm(wasmPath: string) {
+    if (wasmInitialized) return;
+    await initWasm(fs.readFile(wasmPath));
+    wasmInitialized = true;
+}
+
+const fontWeightMap: Record<string, number> = {
+    Normal: 400,
+    Bold: 700,
+    ExtraBold: 800,
+};
+
+function toFontWeight(weight: string): number {
+    return fontWeightMap[weight] ?? 400;
+}
+
+function decodeText(text: string) {
+    return text
+        .replaceAll("&amp;", "&")
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&#39;", "'");
+}
+
+function rgbToCSS(rgb: RGBColor): string {
+    return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
+}
+
+const fontCache = new Map<string, ArrayBuffer>();
+
+/**
+ * Load a font from disk or a remote URL for OG image rendering.
+ *
+ * @internal
+ */
+export async function loadFont(url: string): Promise<ArrayBuffer> {
+    const cached = fontCache.get(url);
+    if (cached) return cached;
+    let buffer: ArrayBuffer;
+    if (/^https?:\/\//.test(url)) {
+        let response: Response;
+        try {
+            response = await fetch(url);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`[northwestern-starlight-theme] Failed to fetch OG font from ${url}: ${message}`, {
+                cause: error,
+            });
+        }
+
+        if (!response.ok) {
+            const statusText = response.statusText ? ` ${response.statusText}` : "";
+            throw new Error(
+                `[northwestern-starlight-theme] Failed to fetch OG font from ${url}: HTTP ${response.status}${statusText}`,
+            );
+        }
+
+        buffer = await response.arrayBuffer();
+    } else {
+        const file = await fs.readFile(url);
+        buffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+    }
+    fontCache.set(url, buffer);
+    return buffer;
+}
+
+const logoCache = new Map<string, string>();
+
+async function loadLogoDataURL(filePath: string): Promise<string> {
+    const cached = logoCache.get(filePath);
+    if (cached) return cached;
+    const buffer = await fs.readFile(filePath);
+    const ext = filePath.split(".").pop()?.toLowerCase() ?? "png";
+    const mime = ext === "svg" ? "image/svg+xml" : `image/${ext}`;
+    const dataURL = `data:${mime};base64,${buffer.toString("base64")}`;
+    logoCache.set(filePath, dataURL);
+    return dataURL;
+}
+
+export async function renderOGImage({
+    resvgWasmPath,
+    title,
+    description = "",
+    bgGradient = [[0, 0, 0]],
+    border: borderConfig = {},
+    padding: rawPadding = 80,
+    logo,
+    font: fontConfig = {},
+    fonts: fontUrls = ["https://api.fontsource.org/v1/fonts/noto-sans/latin-400-normal.ttf"],
+}: OGImageOptions) {
+    const decodedTitle = decodeText(title);
+    const decodedDescription = description ? decodeText(description) : "";
+
+    const [vPad, hPad] = Array.isArray(rawPadding) ? rawPadding : [rawPadding, rawPadding];
+    const borderColor = borderConfig.color ?? [255, 255, 255];
+    const borderWidth = borderConfig.width ?? 0;
+
+    const titleFont = {
+        families: fontConfig.title?.families ?? ["Noto Sans"],
+        size: fontConfig.title?.size ?? 70,
+        weight: fontConfig.title?.weight ?? "Normal",
+        lineHeight: fontConfig.title?.lineHeight ?? 1,
+        color: fontConfig.title?.color ?? ([255, 255, 255] as RGBColor),
+    };
+    const descFont = {
+        families: fontConfig.description?.families ?? ["Noto Sans"],
+        size: fontConfig.description?.size ?? 40,
+        weight: fontConfig.description?.weight ?? "Normal",
+        lineHeight: fontConfig.description?.lineHeight ?? 1.3,
+        color: fontConfig.description?.color ?? ([255, 255, 255] as RGBColor),
+    };
+
+    const fontData = await Promise.all(fontUrls.map(loadFont));
+    const satoriFont = fontUrls.map((url, i) => {
+        const name = url.includes("Poppins") ? "Poppins" : url.includes("Akkurat") ? "Akkurat Pro" : "Noto Sans";
+        return { name, data: fontData[i], weight: 400 as const };
+    });
+
+    const logoDataURL = logo ? await loadLogoDataURL(logo.path) : undefined;
+    const logoW = logo?.size?.[0] ?? 60;
+    const logoH = logo?.size?.[1] ?? logoW;
+
+    const bgStart = rgbToCSS(bgGradient[0]);
+    const bgEnd = bgGradient.length > 1 ? rgbToCSS(bgGradient[bgGradient.length - 1]) : bgStart;
+
+    const element = {
+        type: "div",
+        props: {
+            style: {
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                justifyContent: "center",
+                width: "100%",
+                height: "100%",
+                background: `linear-gradient(to bottom, ${bgStart}, ${bgEnd})`,
+                padding: `${vPad}px ${hPad}px`,
+                paddingLeft: `${hPad + borderWidth}px`,
+                borderLeft: borderWidth ? `${borderWidth}px solid ${rgbToCSS(borderColor)}` : undefined,
+            },
+            children: [
+                ...(logoDataURL
+                    ? [
+                          {
+                              type: "img",
+                              props: {
+                                  src: logoDataURL,
+                                  width: logoW,
+                                  height: logoH,
+                                  style: { marginBottom: "32px" },
+                              },
+                          },
+                      ]
+                    : []),
+                {
+                    type: "div",
+                    props: {
+                        style: {
+                            display: "flex",
+                            flexDirection: "column",
+                            alignItems: "center",
+                            justifyContent: "center",
+                            textAlign: "center",
+                            width: "100%",
+                        },
+                        children: [
+                            {
+                                type: "div",
+                                props: {
+                                    style: {
+                                        fontFamily: titleFont.families[0],
+                                        fontSize: `${titleFont.size}px`,
+                                        fontWeight: toFontWeight(titleFont.weight),
+                                        lineHeight: titleFont.lineHeight,
+                                        color: rgbToCSS(titleFont.color),
+                                        whiteSpace: "pre-wrap",
+                                        textAlign: "center",
+                                    },
+                                    children: decodedTitle,
+                                },
+                            },
+                            ...(decodedDescription
+                                ? [
+                                      {
+                                          type: "div",
+                                          props: {
+                                              style: {
+                                                  fontFamily: descFont.families[0],
+                                                  fontSize: `${descFont.size}px`,
+                                                  fontWeight: toFontWeight(descFont.weight),
+                                                  lineHeight: descFont.lineHeight,
+                                                  color: rgbToCSS(descFont.color),
+                                                  marginTop: "24px",
+                                                  textAlign: "center",
+                                                  maxWidth: "560px",
+                                              },
+                                              children: decodedDescription,
+                                          },
+                                      },
+                                  ]
+                                : []),
+                        ],
+                    },
+                },
+            ],
+        },
+    };
+
+    const svg = await satori(element as any, {
+        width,
+        height,
+        fonts: satoriFont,
+    });
+    await ensureWasm(resvgWasmPath);
+    const resvg = new Resvg(svg, {
+        fitTo: { mode: "width", value: width },
+    });
+
+    return Buffer.from(resvg.render().asPng());
+}

package/src/og/route-middleware.ts

@@ -0,0 +1,125 @@
+import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
+import type { HeadConfig } from "@astrojs/starlight/schemas/head";
+
+type HeadEntry = HeadConfig[number];
+type JsonLd = Record<string, unknown>;
+
+function getStructuredData({
+    imageUrl,
+    isHomepage,
+    isChangelogVersion,
+    logoUrl,
+    pageUrl,
+    siteName,
+    title,
+    description,
+}: {
+    imageUrl: string;
+    isHomepage: boolean;
+    isChangelogVersion: boolean;
+    logoUrl: string;
+    pageUrl: string;
+    siteName: string;
+    title: string;
+    description?: string;
+}): JsonLd {
+    const origin = new URL(pageUrl).origin;
+    const organization = {
+        "@id": `${origin}/#organization`,
+        "@type": "Organization",
+        name: "Northwestern University",
+        url: "https://www.northwestern.edu",
+        logo: logoUrl,
+    };
+    const website = {
+        "@id": `${origin}/#website`,
+        "@type": "WebSite",
+        name: siteName,
+        url: `${origin}/`,
+        description,
+        image: imageUrl,
+        publisher: { "@id": organization["@id"] },
+    };
+
+    if (isHomepage) {
+        return {
+            "@context": "https://schema.org",
+            "@graph": [organization, website],
+        };
+    }
+
+    return {
+        "@context": "https://schema.org",
+        "@graph": [
+            organization,
+            website,
+            {
+                "@type": isChangelogVersion ? "Article" : "TechArticle",
+                headline: title,
+                name: title,
+                description,
+                image: imageUrl,
+                url: pageUrl,
+                mainEntityOfPage: pageUrl,
+                isPartOf: { "@id": website["@id"] },
+                publisher: { "@id": organization["@id"] },
+            },
+        ],
+    };
+}
+
+export const onRequest = defineRouteMiddleware((context) => {
+    const route = context.locals.starlightRoute;
+    const site = context.site;
+    if (!site) return;
+
+    const pageUrl = new URL(context.url.pathname, site).href;
+    const siteName = route.siteTitle ?? route.entry.data.title;
+    const isHomepage = route.id === "index" || context.url.pathname === "/";
+    const isChangelogVersion = route.id?.startsWith("changelog/version/") ?? false;
+    const ogPath = route.id ? `/og/${route.id}.png` : "/og/index.png";
+    const imageUrl = new URL(ogPath, site).href;
+
+    // Replace Starlight's twitter:card (defaults to "summary" on non-splash
+    // pages) with "summary_large_image" so the 1200x630 image isn't cropped.
+    const twitterCardIndex = route.head.findIndex(
+        (entry: HeadEntry) => entry.tag === "meta" && entry.attrs.name === "twitter:card",
+    );
+    if (twitterCardIndex !== -1) {
+        route.head[twitterCardIndex] = {
+            tag: "meta",
+            attrs: { name: "twitter:card", content: "summary_large_image" },
+        };
+    }
+
+    // Resolve the favicon path from Starlight's head tags for og:logo.
+    const faviconEntry = route.head.find(
+        (entry: HeadEntry) => entry.tag === "link" && entry.attrs.rel === "shortcut icon",
+    );
+    const faviconHref = faviconEntry?.attrs.href ?? "/favicon.png";
+    const logoUrl = new URL(faviconHref, site).href;
+    const structuredData = JSON.stringify(
+        getStructuredData({
+            imageUrl,
+            isHomepage,
+            isChangelogVersion,
+            logoUrl,
+            pageUrl,
+            siteName,
+            title: route.entry.data.title,
+            description: route.entry.data.description,
+        }),
+    );
+
+    route.head.push(
+        { tag: "meta", attrs: { property: "og:image", content: imageUrl } },
+        { tag: "meta", attrs: { property: "og:image:type", content: "image/png" } },
+        { tag: "meta", attrs: { property: "og:image:width", content: "1200" } },
+        { tag: "meta", attrs: { property: "og:image:height", content: "630" } },
+        { tag: "meta", attrs: { property: "og:image:alt", content: route.entry.data.title } },
+        { tag: "meta", attrs: { property: "og:logo", content: logoUrl } },
+        { tag: "meta", attrs: { name: "twitter:image", content: imageUrl } },
+        { tag: "meta", attrs: { name: "twitter:image:alt", content: route.entry.data.title } },
+        { tag: "script", attrs: { type: "application/ld+json" }, content: structuredData },
+    );
+});