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

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-03-31
+
+### Added
+
+- **Open Graph image generation**: builds a branded 1200x630 PNG per docs page. Favicon logo, page title, and description on Northwestern purple with a light purple accent border. Slack, Teams, and social media link previews use these images.
+  - Enabled by default. Set `site` in your Astro config. pnpm users: run `pnpm add canvaskit-wasm` to enable (build skips OG gracefully without it).
+  - Disable with `ogImage: false`.
+  - Adds `og:image`, `og:image:type`, `og:image:width`, `og:image:height`, `og:image:alt`, `og:logo`, `twitter:image`, and `twitter:image:alt` meta tags to every page. Overrides `twitter:card` to `summary_large_image`.
+  - New dependency: `astro-og-canvas`.
+
 ## [1.3.2] - 2026-03-30
 
 ### Fixed
@@ -143,7 +153,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI plugin compatibility with method badge preservation
 - Reduced motion support for transitions
 
-[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.3.2...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.3.2...v1.4.0
 [1.3.2]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.2.0...v1.3.0

package/index.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { StarlightPlugin } from "@astrojs/starlight/types";
@@ -92,6 +93,18 @@ export interface NorthwesternThemeConfig {
      * @default true
      */
     mermaid?: boolean | Record<string, unknown>;
+
+    /**
+     * Open Graph image generation.
+     *
+     * Generates branded OG images (1200x630 PNG) for every docs page with the
+     * page title and description on a Northwestern purple background.
+     *
+     * Requires `site` to be set in `astro.config.ts` for absolute image URLs.
+     *
+     * @default true
+     */
+    ogImage?: boolean;
 }
 
 /**
@@ -137,19 +150,30 @@ const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
  * ```
  */
 export default function northwesternTheme(config: NorthwesternThemeConfig = {}): StarlightPlugin {
-    const { homepage = {}, mermaid = true } = config;
+    const { homepage = {}, mermaid = true, ogImage = true } = config;
     const themeConfig = {
         homepage: {
             layout: homepage.layout ?? "centered",
             showTitle: homepage.showTitle ?? true,
             imageWidth: homepage.imageWidth ?? "500px",
         },
+        ogImage: {
+            enabled: false, // set to true in config:setup when ogImage is enabled
+            siteTitle: "",
+            logoPath: "",
+        },
     };
 
     return {
         name: "northwestern-starlight-theme",
         hooks: {
-            async "config:setup"({ config: starlightConfig, updateConfig, addIntegration, logger }) {
+            async "config:setup"({
+                config: starlightConfig,
+                updateConfig,
+                addIntegration,
+                addRouteMiddleware,
+                logger,
+            }) {
                 // Apply default favicon if consumer hasn't set one
                 const consumerSetFavicon =
                     starlightConfig.favicon &&
@@ -244,6 +268,58 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                     }
                 }
 
+                // OG image generation (bundled via astro-og-canvas)
+                if (ogImage) {
+                    // canvaskit-wasm uses __dirname to locate its WASM binary, which
+                    // doesn't exist in ESM. Under pnpm's strict symlinks the binary
+                    // can't be found unless the consumer installs canvaskit-wasm
+                    // directly. Probe resolution from the consumer's project root
+                    // (not the theme package) so a missing install skips OG
+                    // gracefully instead of crashing the build.
+                    let canvaskitUsable = true;
+                    try {
+                        const require = createRequire(join(process.cwd(), "package.json"));
+                        require.resolve("canvaskit-wasm");
+                    } catch {
+                        canvaskitUsable = false;
+                    }
+
+                    if (!canvaskitUsable) {
+                        logger.warn(
+                            "OG image generation requires canvaskit-wasm, which could not be loaded.\n" +
+                                "  pnpm users: run `pnpm add canvaskit-wasm`\n" +
+                                "  The build will continue without OG images.",
+                        );
+                    } else {
+                        themeConfig.ogImage.enabled = true;
+                        themeConfig.ogImage.logoPath = faviconPath;
+                        const rawTitle = starlightConfig.title;
+                        themeConfig.ogImage.siteTitle =
+                            typeof rawTitle === "string"
+                                ? rawTitle
+                                : (Object.values(rawTitle as Record<string, string>)[0] ?? "");
+
+                        addRouteMiddleware({
+                            entrypoint: "@nu-appdev/northwestern-starlight-theme/src/og/route-middleware",
+                            order: "post",
+                        });
+
+                        addIntegration({
+                            name: "northwestern-theme-og-image",
+                            hooks: {
+                                "astro:config:setup": ({ injectRoute }) => {
+                                    injectRoute({
+                                        pattern: "/og/[...slug]",
+                                        entrypoint: "@nu-appdev/northwestern-starlight-theme/src/og/endpoint.ts",
+                                    });
+                                },
+                            },
+                        });
+
+                        logger.info("OG image generation enabled");
+                    }
+                }
+
                 updateConfig({
                     ...(consumerSetFavicon ? {} : { favicon: "/favicon.png" }),
                     components: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -44,6 +44,7 @@
     },
     "./src/styles/components/*": "./src/styles/components/*",
     "./src/components/*": "./src/components/*",
+    "./src/og/*": "./src/og/*",
     "./src/scripts/*": "./src/scripts/*",
     "./src/styles/*": "./src/styles/*"
   },
@@ -56,6 +57,7 @@
   ],
   "dependencies": {
     "@expressive-code/plugin-line-numbers": "^0.41.7",
+    "astro-og-canvas": "^0.10.1",
     "khroma": "^2.1.0"
   },
   "peerDependencies": {

package/src/og/endpoint.ts

@@ -0,0 +1,53 @@
+import { getCollection } from "astro:content";
+import config from "virtual:northwestern-theme/config";
+import { OGImageRoute } from "astro-og-canvas";
+
+const siteTitle = config.ogImage.siteTitle;
+const logoPath = config.ogImage.logoPath;
+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]));
+
+export const { getStaticPaths, GET } = await OGImageRoute({
+    param: "slug",
+    pages,
+    getImageOptions: (path, page) => {
+        const isIndex = path === "index";
+        const isChangelogVersion = path.startsWith("changelog/version/");
+        const title = isIndex ? siteTitle : isChangelogVersion ? `Changelog\n${page.data.title}` : page.data.title;
+        return {
+            title,
+            description: page.data.description,
+            logo: { path: logoPath, size: [60] },
+            bgGradient: [[64, 31, 104]],
+            padding: 120,
+            border: {
+                color: [164, 149, 195],
+                width: 12,
+                side: "inline-start",
+            },
+            font: {
+                title: {
+                    families: ["Poppins"],
+                    weight: "Bold",
+                    size: isChangelogVersion ? 56 : 48,
+                    lineHeight: 1.3,
+                    color: [255, 255, 255],
+                },
+                description: {
+                    families: ["Akkurat Pro"],
+                    size: 28,
+                    lineHeight: 1.5,
+                    color: [182, 172, 209],
+                },
+            },
+            fonts: [
+                "https://common.northwestern.edu/v8/css/fonts/Poppins-Bold.woff",
+                "https://common.northwestern.edu/v8/css/fonts/AkkuratProRegular.woff",
+            ],
+        };
+    },
+});

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 },
+    );
+});

package/src/virtual.d.ts

@@ -14,6 +14,11 @@ declare module "virtual:northwestern-theme/config" {
             showTitle: boolean;
             imageWidth: string;
         };
+        ogImage: {
+            enabled: boolean;
+            siteTitle: string;
+            logoPath: string;
+        };
     };
     export default config;
 }