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

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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
+
+- H1/H2 now use Noto Serif (`--nu-font-display`), H3–H6 use Poppins (`--nu-font-heading`). Sizes, weights, and colors match the [Department 4.0 stylesheet](https://common.northwestern.edu/dept/4.0/css/styles.css).
+- Poppins 400 loaded the Light file instead of Regular. Poppins 500 (Medium) added from v4 CDN.
+- Table headers now use `--nu-purple-100` with white text.
+- Table striping moved to odd rows (`#f9f6ff`); dark mode uses `rgb(78 42 132 / 10%)`.
+- `--nu-purple-surface` corrected to `#f9f6ff`, `--nu-purple-surface-subtle` to `#f3f0f7`.
+- Blockquote background uses `#f9f6ff` instead of translucent purple.
+- Horizontal rules use 3px `--nu-purple-10` instead of 1px gray.
+- List markers use `--nu-purple-100` instead of `--nu-purple-40`.
+
 ## [1.3.1] - 2026-03-27
 
 ### Fixed
@@ -130,7 +153,9 @@ 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.1...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
 [1.2.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.1.1...v1.2.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.1",
+  "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/components/Hero.astro

@@ -130,6 +130,7 @@ const imageWidth = themeConfig.homepage.imageWidth;
         line-height: var(--sl-line-height-headings);
         font-weight: 600;
         color: var(--nu-purple-100);
+        box-shadow: none;
     }
 
     :root:not([data-theme="light"]) h1 {

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/styles/components/blockquotes.css

@@ -7,8 +7,9 @@
         padding: 1rem 1.5rem;
         margin: 2rem 0;
         color: var(--nu-color-text);
-        background: rgb(228 224 238 / 42%);
+        background: #f9f6ff;
         border-inline-start: 10px solid var(--nu-purple-100);
+        border-radius: 0 0.75rem 0.75rem 0 !important;
     }
 
     .sl-markdown-content blockquote:not(:where(.not-content *)) p:last-child {

package/src/styles/components/property-table.css

@@ -557,6 +557,7 @@
         .nu-property-table:not(.nu-property-table--table) .nu-property__head {
             flex-direction: column;
             gap: 0.25rem;
+            align-items: flex-start;
         }
 
         .nu-property-table:not(.nu-property-table--table) .nu-property__prop-col {

package/src/styles/components/tables.css

@@ -16,18 +16,20 @@
     }
 
     .sl-markdown-content table:not(:where(.not-content *)) > thead > tr > th {
-        padding: 0.5rem 1rem;
-        font-family: var(--nu-font-heading);
-        font-weight: 600;
-        color: var(--nu-black-80);
+        padding: 0.75rem 0.5rem;
+        font-family: var(--nu-font-body);
+        font-size: 1rem;
+        font-weight: 700;
+        color: #fff;
         text-align: left;
-        background-color: var(--nu-purple-surface);
+        background-color: var(--nu-purple-100);
         border: 1px solid var(--nu-border-color);
+        border-right: 1px solid rgb(255 255 255 / 30%);
+        border-left: 1px solid rgb(255 255 255 / 30%);
     }
 
     :root:not([data-theme="light"]) .sl-markdown-content table:not(:where(.not-content *)) > thead > tr > th {
-        color: var(--nu-color-text);
-        background-color: rgb(78 42 132 / 14%);
+        background-color: rgb(78 42 132 / 40%);
     }
 
     .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr > td {
@@ -46,15 +48,19 @@
         text-align: center;
     }
 
-    .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr:nth-child(even) {
-        background-color: #f3f4f6;
+    .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr:nth-child(odd) {
+        background-color: #f9f6ff;
+    }
+
+    .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr:hover {
+        background-color: #f0f0f0;
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr:nth-child(odd) {
+        background-color: rgb(78 42 132 / 10%);
     }
 
-    :root:not([data-theme="light"])
-        .sl-markdown-content
-        table:not(:where(.not-content *))
-        > tbody
-        > tr:nth-child(even) {
-        background-color: #1e1e1e;
+    :root:not([data-theme="light"]) .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr:hover {
+        background-color: rgb(255 255 255 / 5%);
     }
 }

package/src/styles/content.css

@@ -39,7 +39,7 @@
         width: 6px;
         height: 6px;
         content: "";
-        background: var(--nu-purple-40);
+        background: var(--nu-purple-100);
     }
 
     :root:not([data-theme="light"]) .sl-markdown-content ul:not(:where(.not-content *)) > li::before {
@@ -56,10 +56,16 @@
         border-color: var(--nu-purple-30);
     }
 
+    .sl-markdown-content mark:not(:where(.not-content *)),
+    .sl-markdown-content .highlight:not(:where(.not-content *)) {
+        padding: 3px;
+        background: rgb(228 224 238 / 50%);
+    }
+
     .sl-markdown-content hr:not(:where(.not-content *)) {
-        height: 1px;
+        height: 3px;
         margin: 2.5rem 0;
-        background: var(--nu-border-color);
+        background: var(--nu-purple-10);
         border: 0;
     }
 

package/src/styles/typography.css

@@ -78,7 +78,15 @@
     font-family: Poppins;
     font-style: normal;
     font-weight: 400;
-    src: url("https://common.northwestern.edu/v8/css/fonts/Poppins-Light.woff") format("woff");
+    src: url("https://common.northwestern.edu/v8/css/fonts/Poppins-Regular.woff") format("woff");
+    font-display: swap;
+}
+
+@font-face {
+    font-family: Poppins;
+    font-style: normal;
+    font-weight: 500;
+    src: url("https://common.northwestern.edu/dept/4.0/css/fonts/poppins/poppins-v21-latin-500.woff2") format("woff2");
     font-display: swap;
 }
 
@@ -150,18 +158,81 @@
 
     h1,
     h2 {
-        font-family: var(--nu-font-heading);
-    }
-
-    h1 {
-        color: var(--sl-color-text-accent);
+        font-family: var(--nu-font-display);
     }
 
     h3,
     h4,
     h5,
     h6 {
-        font-family: var(--nu-font-body);
+        font-family: var(--nu-font-heading);
+    }
+
+    .main-pane h1 {
+        display: inline;
+        font-size: clamp(2rem, 1rem + 3vw, 2.8125rem);
+        font-weight: 500;
+        line-height: 1.4;
+        color: #000;
+        box-shadow: inset 0 -0.55em 0 0 var(--nu-purple-10);
+        box-decoration-break: clone;
+    }
+
+    :root:not([data-theme="light"]) .main-pane h1 {
+        color: #fff;
+        box-shadow: inset 0 -0.55em 0 0 var(--nu-purple-140);
+    }
+
+    .sl-markdown-content h2 {
+        font-size: 1.875rem;
+        font-weight: 700;
+        line-height: 1.4;
+        color: var(--nu-purple-120);
+    }
+
+    .sl-markdown-content h3 {
+        font-size: 1.625rem;
+        font-weight: 500;
+        line-height: 1.4;
+        color: var(--nu-black-80);
+    }
+
+    .sl-markdown-content h4 {
+        font-size: 1.4375rem;
+        font-weight: 500;
+        line-height: 1.4;
+        color: var(--nu-purple-120);
+    }
+
+    .sl-markdown-content h5 {
+        font-size: 1.25rem;
+        font-weight: 500;
+        line-height: 1.4;
+        color: var(--nu-black-80);
+    }
+
+    .sl-markdown-content h6 {
+        font-size: 1.125rem;
+        font-weight: 500;
+        line-height: 1.4;
+        color: var(--nu-black-80);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content h2 {
+        color: var(--nu-purple-30);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content h3 {
+        color: var(--nu-color-text);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content h4 {
+        color: var(--nu-purple-30);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content h5,
+    :root:not([data-theme="light"]) .sl-markdown-content h6 {
+        color: var(--nu-color-text);
     }
 
     .site-title {

package/src/styles/variables.css

@@ -55,12 +55,12 @@
         --nu-transition-default: 200ms ease;
         --nu-transition-slow: 300ms ease-in-out;
 
-        --nu-purple-surface: #f3f0f7;
-        --nu-purple-surface-subtle: #f7f5f9;
+        --nu-purple-surface: #f9f6ff;
+        --nu-purple-surface-subtle: #f3f0f7;
         --nu-purple-tint: rgb(78 42 132 / 15%);
         --nu-purple-tint-strong: rgb(78 42 132 / 20%);
         --nu-surface-muted: #f9fafb;
-        --nu-hover-bg: #f3f4f6;
+        --nu-hover-bg: #f0f0f0;
 
         --nu-focus-ring: var(--nu-purple-100);
         --nu-focus-border: #a795c2;
@@ -90,10 +90,10 @@
         --nu-focus-ring: var(--nu-purple-100);
         --nu-focus-shadow-color: rgb(78 42 132 / 25%);
 
-        --nu-purple-surface: #f3f0f7;
-        --nu-purple-surface-subtle: #f7f5f9;
+        --nu-purple-surface: #f9f6ff;
+        --nu-purple-surface-subtle: #f3f0f7;
         --nu-surface-muted: #f9fafb;
-        --nu-hover-bg: #f3f4f6;
+        --nu-hover-bg: #f0f0f0;
     }
 
     :root:not([data-theme="light"]),

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;
 }