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

package/dist/legacy-html-redirects.d.ts

@@ -0,0 +1,72 @@
+import type { AstroIntegration } from "astro";
+/**
+ * Options for {@link generateLegacyHtmlRedirects} and the wrapped integration
+ * in {@link legacyHtmlRedirectsIntegration}.
+ */
+export interface LegacyHtmlRedirectsOptions {
+    /**
+     * Project-relative path to the Markdown/MDX content root.
+     *
+     * @default "src/content/docs"
+     */
+    contentDir?: string;
+}
+/**
+ * Build a `{ "/<slug>.html": "/<slug>/" }` map for every Markdown/MDX page
+ * under the content directory. Intended for sites migrated from VuePress, where
+ * pages were served at `<slug>.html` instead of `<slug>/`. Pass the result into
+ * Astro's `redirects` config — old external links then resolve to the new
+ * canonical URL.
+ *
+ * Pair with {@link legacyHtmlRedirectsIntegration} so the generated redirect
+ * pages preserve the URL hash fragment. Prefer
+ * {@link defineNorthwesternConfig}'s `legacyHtmlRedirects` option, which wires
+ * both together.
+ *
+ * Index files are mapped to their parent slug (e.g. `dev/fc/index.md` becomes
+ * `/dev/fc.html → /dev/fc/`); the root `index.{md,mdx}` is skipped.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *     redirects: generateLegacyHtmlRedirects(),
+ * });
+ * ```
+ */
+export declare function generateLegacyHtmlRedirects(options?: LegacyHtmlRedirectsOptions): Record<string, string>;
+/**
+ * Astro integration that post-processes the static redirect pages produced for
+ * `.html` sources so legacy deep links keep their URL hash.
+ *
+ * Two things happen after the build:
+ * 1. **Flatten the directory layout.** Astro's default `directory` build format
+ *    writes each redirect to `<path>.html/index.html`. GitHub Pages serves
+ *    those via a 301 that appends a trailing slash — an unnecessary hop.
+ *    Rewriting them as flat `<path>.html` files cuts the round-trip.
+ * 2. **Preserve the URL hash.** Astro's redirect page uses a `<meta refresh>`
+ *    tag, which drops the fragment because the target URL has none of its own.
+ *    A small inline `<script>` calls `location.replace(target + location.hash)`
+ *    first; the meta-refresh is wrapped in `<noscript>` as the no-JS fallback.
+ *    Running both unconditionally races and loses the hash.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *     integrations: [legacyHtmlRedirectsIntegration()],
+ *     redirects: generateLegacyHtmlRedirects(),
+ * });
+ * ```
+ */
+export declare function legacyHtmlRedirectsIntegration(): AstroIntegration;
+/** @internal — exposed for unit tests. */
+export declare function flattenHtmlRedirectDirs(distDir: string): void;
+/**
+ * Rewrite a static redirect page so forwarding preserves the URL hash.
+ *
+ * Returns the page unchanged if no `<meta http-equiv="refresh">` is present,
+ * the tag is missing a `url=` target, or the page has already been rewritten.
+ *
+ * @internal — exposed for unit tests.
+ */
+export declare function rewriteRedirectPage(html: string): string;
+//# sourceMappingURL=legacy-html-redirects.d.ts.map

package/dist/legacy-html-redirects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-html-redirects.d.ts","sourceRoot":"","sources":["../legacy-html-redirects.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG9C;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB5G;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,IAAI,gBAAgB,CASjE;AAED,0CAA0C;AAC1C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AAuCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWxD"}

package/dist/mermaid.d.ts

@@ -0,0 +1,97 @@
+import type { AstroIntegration } from "astro";
+import type { AstroMermaidOptions } from "astro-mermaid";
+/**
+ * Configuration options for the Northwestern Mermaid integration.
+ *
+ * Extends `astro-mermaid` options with a `toolbar` toggle that controls
+ * the hover toolbar (fullscreen, download, copy) on rendered diagrams.
+ *
+ * @see {@link northwesternMermaid} for the integration factory
+ */
+export interface NorthwesternMermaidOptions extends AstroMermaidOptions {
+    /**
+     * Show the hover toolbar (fullscreen, download SVG, copy source) on diagrams.
+     *
+     * @default true
+     */
+    toolbar?: boolean;
+}
+/**
+ * Theme mode for Mermaid color palette generation.
+ *
+ * Maps to the `data-theme` attribute on `<html>`: `"light"` for the default
+ * palette, `"dark"` for the inverted palette with lighter primary colors
+ * and darker canvas backgrounds.
+ */
+export type NorthwesternMermaidMode = "light" | "dark";
+/**
+ * Generate a complete `astro-mermaid` config with Northwestern-branded colors
+ * for the given theme mode.
+ *
+ * Builds a Mermaid `themeVariables` object from the Northwestern brand palette,
+ * deriving all node, edge, label, chart, and diagram-specific colors from a
+ * small set of brand primaries via `khroma` color manipulation.
+ *
+ * @param mode - `"light"` or `"dark"`. Controls canvas, text, and primary color values.
+ * @returns A complete `AstroMermaidOptions` object ready to pass to `astro-mermaid`.
+ *
+ * @example
+ * ```ts
+ * import { createNorthwesternMermaidConfig } from "@nu-appdev/northwestern-starlight-theme/mermaid";
+ *
+ * const darkConfig = createNorthwesternMermaidConfig("dark");
+ * // darkConfig.mermaidConfig.themeVariables contains all colors
+ * ```
+ */
+export declare function createNorthwesternMermaidConfig(mode: NorthwesternMermaidMode): AstroMermaidOptions;
+/**
+ * Pre-built light-mode Mermaid config with Northwestern brand colors.
+ *
+ * Used as the default when Mermaid is auto-detected. Override individual
+ * `themeVariables` by passing a `mermaid` object to {@link northwesternTheme}
+ * in `index.ts`, or use {@link createNorthwesternMermaidConfig} for full control.
+ */
+export declare const defaultMermaidConfig: AstroMermaidOptions;
+/**
+ * Pre-built dark-mode Mermaid config with Northwestern brand colors.
+ *
+ * Applied at runtime when the user switches to dark mode. The toolbar script
+ * re-renders diagrams with this config via `window.__NU_MERMAID_CONFIGS__.dark`.
+ */
+export declare const darkMermaidConfig: AstroMermaidOptions;
+/**
+ * Create an Astro integration that registers Northwestern-branded Mermaid diagrams.
+ *
+ * Wraps `astro-mermaid` with Northwestern color palettes for both light and dark
+ * modes, and injects the toolbar script (fullscreen viewer, download, copy).
+ *
+ * **Note:** `defineNorthwesternConfig` handles Mermaid integration ordering.
+ * This function is only needed for manual setups.
+ *
+ * **Must be added before `starlight()` in the `integrations` array.** The
+ * `astro-mermaid` remark plugin needs to register before Starlight's rehype
+ * processing, and Astro processes integrations in order. Placing it after
+ * `starlight()` causes Mermaid code blocks to be treated as plain code.
+ *
+ * @param options - Merged with Northwestern defaults. Set `toolbar: false` to
+ *   disable the hover toolbar.
+ * @returns An Astro integration to add to `integrations` in your Astro config.
+ *
+ * @example Manual setup
+ * ```ts
+ * import { northwesternMermaid } from "@nu-appdev/northwestern-starlight-theme/mermaid";
+ * import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
+ *
+ * export default defineConfig({
+ *     integrations: [
+ *         northwesternMermaid(), // Must come before starlight()
+ *         starlight({
+ *             plugins: [northwesternTheme()],
+ *             title: "My Docs",
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+export declare function northwesternMermaid(options?: NorthwesternMermaidOptions): AstroIntegration;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../mermaid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIzD;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACnE;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,MAAM,CAAC;AAwUvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAmBlG;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,mBAA8D,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,gBAAgB,CAqD9F"}

package/dist/src/config-schema.d.ts

@@ -0,0 +1,161 @@
+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 declare const nonEmptyStringSchema: z.ZodString;
+/**
+ * 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 declare const northwesternThemeConfigSchema: z.ZodObject<{
+    /**
+     * Homepage hero layout configuration.
+     */
+    homepage: z.ZodOptional<z.ZodObject<{
+        layout: z.ZodOptional<z.ZodEnum<{
+            centered: "centered";
+            split: "split";
+        }>>;
+        showTitle: z.ZodOptional<z.ZodBoolean>;
+        imageWidth: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    /**
+     * 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.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    /**
+     * Open Graph image generation.
+     *
+     * Generates a branded 1200x630 image for each docs page when `site`
+     * is configured in `astro.config.ts`.
+     */
+    ogImage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * 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 declare const northwesternMermaidOptionsSchema: z.ZodObject<{
+    /**
+     * Show the hover toolbar on rendered diagrams.
+     *
+     * The toolbar provides fullscreen, download, and copy-source actions.
+     */
+    toolbar: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/**
+ * Options for the legacy `.html` redirect helper.
+ *
+ * Accepts the content directory override. The schema is strict so typos in
+ * the option bag surface as validation errors instead of being ignored.
+ */
+export declare const legacyHtmlRedirectsOptionsSchema: z.ZodObject<{
+    contentDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 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 declare const northwesternConfigOptionsSchema: z.ZodObject<{
+    /**
+     * Full Starlight configuration object.
+     *
+     * This is forwarded to `starlight()` after Northwestern defaults and
+     * helper-managed integration ordering are applied.
+     */
+    starlight: z.ZodObject<{}, z.core.$loose>;
+    /**
+     * Northwestern theme plugin options.
+     */
+    theme: z.ZodOptional<z.ZodObject<{
+        /**
+         * Homepage hero layout configuration.
+         */
+        homepage: z.ZodOptional<z.ZodObject<{
+            layout: z.ZodOptional<z.ZodEnum<{
+                centered: "centered";
+                split: "split";
+            }>>;
+            showTitle: z.ZodOptional<z.ZodBoolean>;
+            imageWidth: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        /**
+         * 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.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        /**
+         * Open Graph image generation.
+         *
+         * Generates a branded 1200x630 image for each docs page when `site`
+         * is configured in `astro.config.ts`.
+         */
+        ogImage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    /**
+     * Mermaid diagram support.
+     *
+     * - `true`: add Northwestern Mermaid with defaults
+     * - `false`: disable Mermaid
+     * - `object`: add Northwestern Mermaid with custom options
+     */
+    mermaid: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        /**
+         * Show the hover toolbar on rendered diagrams.
+         *
+         * The toolbar provides fullscreen, download, and copy-source actions.
+         */
+        toolbar: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>]>>;
+    /**
+     * Additional Starlight plugins to register after the Northwestern theme.
+     */
+    plugins: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    /**
+     * Generate `.html` redirects for every content page and rewrite the
+     * emitted redirect pages so the URL hash is preserved on forward.
+     *
+     * - `true`: scan `src/content/docs` with the defaults
+     * - `false` (default): do nothing
+     * - `object`: scan a custom content directory
+     */
+    legacyHtmlRedirects: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        contentDir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    /**
+     * 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.ZodOptional<z.ZodObject<{
+        /**
+         * Integrations added before Mermaid and Starlight.
+         */
+        before: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        /**
+         * Integrations added after Starlight.
+         */
+        after: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+/**
+ * Validate a public config object and throw a friendly package-scoped error on failure.
+ */
+export declare function validateSchema<T>(schema: z.ZodType<T>, value: unknown, scope: string): T;
+//# sourceMappingURL=config-schema.d.ts.map

package/dist/src/config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["../../src/config-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,aAIoD,CAAC;AA6DtF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;IAElC;;OAEG;;;;;;;;;IAKH;;;;;;OAMG;;IASH;;;;;OAKG;;kBAOL,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC;IAErC;;;;OAIG;;iBAQL,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC;;kBAcvC,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;IAEpC;;;;;OAKG;;IAKH;;OAEG;;QApGH;;WAEG;;;;;;;;;QAKH;;;;;;WAMG;;QASH;;;;;WAKG;;;IA8EH;;;;;;OAMG;;QAnEH;;;;WAIG;;;IAqEH;;OAEG;;IAKH;;;;;;;OAOG;;;;IAMH;;;;;OAKG;;QAGK;;WAEG;;QAKH;;WAEG;;;iBAYb,CAAC;AA2BP;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAQxF"}

package/dist/src/rehype-table-scroll.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rehype plugin that wraps `<table>` elements in a scrollable container at build time.
+ *
+ * Inserts a `<div class="nu-table-scroll">` around each table with `tabindex="0"`,
+ * `role="region"`, and `aria-label` for keyboard scrollability. Runs during the
+ * Astro build so the HTML arrives with the wrapper already in place.
+ */
+import type { Root } from "hast";
+export default function rehypeTableScroll(): (tree: Root) => void;
+//# sourceMappingURL=rehype-table-scroll.d.ts.map

package/dist/src/rehype-table-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehype-table-scroll.d.ts","sourceRoot":"","sources":["../../src/rehype-table-scroll.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAkB,IAAI,EAAE,MAAM,MAAM,CAAC;AAgCjD,MAAM,CAAC,OAAO,UAAU,iBAAiB,KAC7B,MAAM,IAAI,UACrB"}

package/expressive-code.ts

@@ -0,0 +1,35 @@
+import type { StarlightExpressiveCodeOptions } from "@astrojs/starlight/expressive-code";
+import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
+
+/**
+ * Pre-configured Expressive Code options for the Northwestern Starlight theme.
+ *
+ * Adds the line-numbers plugin and sets sensible defaults. Pass your own
+ * options to merge with the Northwestern defaults.
+ *
+ * **Note:** `defineNorthwesternConfig` includes these options.
+ * This helper is only needed for manual setups using `northwesternTheme()` directly.
+ *
+ * @example
+ * ```ts
+ * // ec.config.mjs (manual setup only)
+ * import { defineEcConfig } from "@astrojs/starlight/expressive-code";
+ * import { northwesternExpressiveCode } from "@nu-appdev/northwestern-starlight-theme/expressive-code";
+ *
+ * export default defineEcConfig(northwesternExpressiveCode());
+ * ```
+ */
+export function northwesternExpressiveCode(
+    config: StarlightExpressiveCodeOptions = {},
+): StarlightExpressiveCodeOptions {
+    const { defaultProps, plugins, ...rest } = config;
+
+    return {
+        ...rest,
+        plugins: [pluginLineNumbers(), ...(plugins ?? [])],
+        defaultProps: {
+            showLineNumbers: false,
+            ...(defaultProps ?? {}),
+        },
+    };
+}

package/index.ts

@@ -4,7 +4,8 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { StarlightPlugin } from "@astrojs/starlight/types";
-import rehypeTableScroll from "./src/rehype-table-scroll.ts";
+import { nonEmptyStringSchema, northwesternThemeConfigSchema, validateSchema } from "./src/config-schema";
+import rehypeTableScroll from "./src/rehype-table-scroll";
 
 /**
  * Configuration for the homepage hero section.
@@ -54,21 +55,16 @@ export interface NorthwesternHomepageConfig {
 /**
  * Top-level configuration for the Northwestern Starlight theme plugin.
  *
- * Pass to {@link northwesternTheme} when registering the plugin in your
- * Starlight config. All properties are optional and have sensible defaults.
+ * With `defineNorthwesternConfig`, pass these as the `theme` key.
+ * With `northwesternTheme()` directly, pass them as the function argument.
+ * All properties are optional.
  *
  * @example
  * ```ts
- * // astro.config.ts
- * import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
- *
- * export default defineConfig({
- *     integrations: [
- *         starlight({
- *             plugins: [northwesternTheme({ homepage: { layout: "split" } })],
- *         }),
- *     ],
- * });
+ * defineNorthwesternConfig({
+ *     starlight: { title: "My Docs" },
+ *     theme: { homepage: { layout: "split" } },
+ * })
  * ```
  *
  * @see {@link NorthwesternHomepageConfig} for homepage hero options
@@ -87,8 +83,7 @@ export interface NorthwesternThemeConfig {
      * - `true` (default) — auto-detect: enables Mermaid if `astro-mermaid` and `mermaid`
      *   are installed, skips silently if they are not
      * - `false` — disables Mermaid entirely
-     * - `object` — enables Mermaid with custom {@link https://mermaid.js.org/config/schema-docs/config.html | MermaidConfig}
-     *   merged with Northwestern defaults
+     * - `object` — enables Mermaid with custom Mermaid config merged with Northwestern defaults
      *
      * @default true
      */
@@ -107,6 +102,18 @@ export interface NorthwesternThemeConfig {
     ogImage?: boolean;
 }
 
+function getSiteTitle(title: unknown): string {
+    const parsedTitle = nonEmptyStringSchema.safeParse(title);
+    if (parsedTitle.success) return parsedTitle.data;
+    if (title && typeof title === "object") {
+        for (const value of Object.values(title as Record<string, unknown>)) {
+            const parsedValue = nonEmptyStringSchema.safeParse(value);
+            if (parsedValue.success) return parsedValue.data;
+        }
+    }
+    return "";
+}
+
 /**
  * Try to resolve a module. Returns true if it can be imported.
  */
@@ -129,10 +136,14 @@ const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
  * component overrides (Hero, ThemeToggle, EditLink), and optional Mermaid diagram
  * support with branded color schemes.
  *
+ * **Recommended:** Use {@link https://github.com/NUAppDev/northwestern-starlight-theme | defineNorthwesternConfig}
+ * from `@nu-appdev/northwestern-starlight-theme/config` instead. It handles
+ * integration ordering, Mermaid, and Expressive Code (line numbers, GitHub themes).
+ *
  * @param config - Theme configuration. All properties optional.
  * @returns A Starlight plugin to pass to `plugins` in your Starlight config.
  *
- * @example Basic usage (all defaults)
+ * @example Manual setup
  * ```ts
  * starlight({ plugins: [northwesternTheme()] })
  * ```
@@ -150,7 +161,11 @@ const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
  * ```
  */
 export default function northwesternTheme(config: NorthwesternThemeConfig = {}): StarlightPlugin {
-    const { homepage = {}, mermaid = true, ogImage = true } = config;
+    const {
+        homepage = {},
+        mermaid = true,
+        ogImage = true,
+    } = validateSchema(northwesternThemeConfigSchema, config, "theme config");
     const themeConfig = {
         homepage: {
             layout: homepage.layout ?? "centered",
@@ -161,6 +176,7 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
             enabled: false, // set to true in config:setup when ogImage is enabled
             siteTitle: "",
             logoPath: "",
+            resvgWasmPath: "",
         },
     };
 
@@ -268,36 +284,18 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                     }
                 }
 
-                // OG image generation (bundled via astro-og-canvas)
+                // OG image generation (bundled via satori + @resvg/resvg-wasm)
                 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;
-                    }
+                    const siteTitle = getSiteTitle(starlightConfig.title);
 
-                    if (!canvaskitUsable) {
+                    if (!siteTitle) {
                         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.",
+                            "Open Graph image generation was disabled because Starlight `title` is empty.\n" +
+                                "  Set `title` in starlight({...}) so OG images and structured data have a site name.",
                         );
                     } 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] ?? "");
+                        themeConfig.ogImage.siteTitle = siteTitle;
 
                         addRouteMiddleware({
                             entrypoint: "@nu-appdev/northwestern-starlight-theme/src/og/route-middleware",
@@ -307,16 +305,29 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                         addIntegration({
                             name: "northwestern-theme-og-image",
                             hooks: {
-                                "astro:config:setup": ({ injectRoute }) => {
+                                "astro:config:setup": ({ config: astroConfig, injectRoute }) => {
+                                    if (!astroConfig.site) {
+                                        logger.warn(
+                                            "Open Graph image generation was disabled because `site` is not set.\n" +
+                                                "  Set `site` in astro.config.ts to enable absolute OG image URLs.",
+                                        );
+                                        return;
+                                    }
+
+                                    themeConfig.ogImage.enabled = true;
+                                    const require = createRequire(import.meta.url);
+                                    themeConfig.ogImage.resvgWasmPath = require.resolve(
+                                        "@resvg/resvg-wasm/index_bg.wasm",
+                                    );
+
                                     injectRoute({
                                         pattern: "/og/[...slug]",
                                         entrypoint: "@nu-appdev/northwestern-starlight-theme/src/og/endpoint.ts",
                                     });
+                                    logger.info("OG image generation enabled");
                                 },
                             },
                         });
-
-                        logger.info("OG image generation enabled");
                     }
                 }