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

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-03-31
+
+### Added
+
+- **[`defineNorthwesternConfig`](http://starlight-theme.entapp.northwestern.edu/getting-started/#configuration) config helper.** Single function that returns a complete Astro config with integration ordering (mermaid → starlight), plugin registration, and Expressive Code. Replaces the manual `defineConfig` + `starlight()` + `northwesternMermaid()` wiring. New `./config` package export.
+- **Automatic Expressive Code line numbers.** `defineNorthwesternConfig` injects `pluginLineNumbers()` and GitHub syntax themes (`github-dark` / `github-light`). No `ec.config.mjs` file needed. A Vite plugin separates serializable config from plugin instances so the `<Code>` Astro component continues to work.
+- Type declarations (`.d.ts`) shipped for all public exports.
+- OG images for changelog version pages with multi-line titles (e.g., "Changelog / 1.4.0").
+- JSON-LD structured data on each page.
+- Unit test suite (Vitest) covering `config.ts`, `expressive-code.ts`, `mermaid.ts`, and `rehype-table-scroll.ts`. E2E tests moved to `tests/e2e/`. CI runs unit tests in a dedicated job.
+
+### Fixed
+
+- Replaced `astro-og-canvas` + `canvaskit-wasm` with `satori` + `@resvg/resvg-wasm`. pnpm users no longer need `canvaskit-wasm` as a direct dependency.
+- OG image generation logs a warning and disables when Starlight `title` is empty or `site` is not set, instead of crashing or producing broken URLs.
+- OG font buffer uses correct `Uint8Array` offset slicing instead of casting the full backing `ArrayBuffer`.
+- Larger OG text: title 48→56px, description 28→32px, logo 60→80px. Separate vertical (60px) and horizontal (220px) padding to avoid clipping.
+- Runtime config validation now catches invalid theme, Mermaid, and config-helper options with friendly errors at the public API boundary instead of failing later with cryptic behavior.
+- Rehype table scroll skips tables already inside `.nu-table-scroll`, preventing double-wrapping on incremental rebuilds.
+- Aside borders use solid brand colors (`#5091cd`, `#008656`, `#ffc520`, `#ef553f`) and a 3px left accent stripe instead of a translucent 1px box border. Dark mode borders match the text accent for each variant.
+
+### Changed
+
+- `h1` keeps `Noto Serif`; `h2`–`h6` switched to `Poppins`.
+- Package `exports` map includes `types` fields pointing to `dist/*.d.ts` for all entry points.
+
 ## [1.4.0] - 2026-03-31
 
 ### Added
@@ -153,7 +179,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.4.0...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.4.0...v1.5.0
 [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

package/README.md

@@ -20,21 +20,17 @@ pnpm add @nu-appdev/northwestern-starlight-theme
 ```
 
 ```ts
-import starlight from "@astrojs/starlight";
-import { defineConfig } from "astro/config";
-import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
-
-export default defineConfig({
-    integrations: [
-        starlight({
-            plugins: [northwesternTheme()],
-            title: "My Docs",
-        }),
-    ],
+import { defineNorthwesternConfig } from "@nu-appdev/northwestern-starlight-theme/config";
+
+export default defineNorthwesternConfig({
+    site: "https://docs.example.northwestern.edu",
+    starlight: {
+        title: "My Docs",
+    },
 });
 ```
 
-The plugin applies Northwestern's purple palette, Akkurat Pro + Poppins typography, branded navigation, styled components, and full dark mode support. No additional CSS or configuration required.
+The helper applies Northwestern's purple palette, Akkurat Pro + Poppins typography, branded navigation, styled components, and dark mode. It handles integration ordering, plugin registration, and Mermaid setup.
 
 See the **[documentation](https://starlight-theme.entapp.northwestern.edu)** for setup options, customization, and component examples.
 

package/config.ts

@@ -0,0 +1,308 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import starlight from "@astrojs/starlight";
+import type { StarlightExpressiveCodeOptions } from "@astrojs/starlight/expressive-code";
+import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
+import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
+import type { AstroIntegration, AstroUserConfig } from "astro";
+import type { NorthwesternThemeConfig } from "./index";
+import northwesternTheme from "./index";
+import { type NorthwesternMermaidOptions, northwesternMermaid } from "./mermaid";
+import { northwesternConfigOptionsSchema, validateSchema } from "./src/config-schema";
+
+/**
+ * Vite plugin that enables `pluginLineNumbers` for both markdown code blocks
+ * and the `<Code>` component without requiring a manual `ec.config.mjs` file.
+ *
+ * Expressive Code serializes inline config via JSON.stringify for the `<Code>`
+ * component's virtual module. Plugin instances aren't serializable, causing a
+ * build error when any page uses `<Code>`.
+ *
+ * This plugin:
+ * 1. Strips non-serializable `plugins` from the virtual config module
+ *    (so the `<Code>` component's serialization check passes)
+ * 2. Provides a virtual `ec.config.mjs` that re-exports the plugins
+ *    (so the `<Code>` component picks them up at render time via merge)
+ *
+ * If the user has a real `ec.config.mjs` on disk, this plugin does nothing.
+ */
+function northwesternEcVitePlugin() {
+    const _require = createRequire(import.meta.url);
+    const resolvedPluginPath = _require.resolve("@expressive-code/plugin-line-numbers").replaceAll("\\", "/");
+    let hasRealEcConfig = false;
+
+    return {
+        name: "northwestern-ec-compat",
+        configResolved(config: { root: string }) {
+            hasRealEcConfig = existsSync(join(config.root, "ec.config.mjs"));
+        },
+        resolveId(id: string) {
+            if (!hasRealEcConfig && id === "./ec.config.mjs") {
+                return "\0northwestern-virtual-ec-config";
+            }
+        },
+        load(id: string) {
+            if (id === "\0northwestern-virtual-ec-config") {
+                return [
+                    `import { pluginLineNumbers } from "${resolvedPluginPath}";`,
+                    "export default { plugins: [pluginLineNumbers()] };",
+                ].join("\n");
+            }
+        },
+        transform(code: string, id: string) {
+            if (!hasRealEcConfig && id === "\0virtual:astro-expressive-code/config") {
+                return code.replace(/export const ecIntegrationOptions = ({.*})/, (match: string, json: string) => {
+                    try {
+                        const parsed = JSON.parse(json);
+                        delete parsed.plugins;
+                        return `export const ecIntegrationOptions = ${JSON.stringify(parsed)}`;
+                    } catch {
+                        return match;
+                    }
+                });
+            }
+        },
+    };
+}
+
+function hasOptionalPackage(id: string): boolean {
+    const _require = createRequire(import.meta.url);
+
+    try {
+        _require.resolve(id);
+        return true;
+    } catch (error) {
+        // Some ESM-only packages expose only an `import` condition, so
+        // `require.resolve()` can fail even when the package is installed.
+        if (error && typeof error === "object" && "code" in error && error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
+            return true;
+        }
+
+        return false;
+    }
+}
+
+/**
+ * Merge helper-managed and migrated Starlight plugins into a stable order.
+ *
+ * The Northwestern theme plugin is always first. Existing `starlight.plugins`
+ * are preserved next for migration compatibility, and helper-level `plugins`
+ * are appended last. Named plugins are deduped by first occurrence.
+ *
+ * @internal
+ */
+export function mergeStarlightPlugins(
+    themePlugin: StarlightPlugin,
+    starlightPlugins: StarlightPlugin[],
+    helperPlugins: StarlightPlugin[],
+): StarlightPlugin[] {
+    const seenNamedPlugins = new Set<string>();
+    const deduped: StarlightPlugin[] = [];
+
+    for (const plugin of [themePlugin, ...starlightPlugins, ...helperPlugins]) {
+        if (!plugin.name) {
+            deduped.push(plugin);
+            continue;
+        }
+
+        if (seenNamedPlugins.has(plugin.name)) {
+            continue;
+        }
+
+        seenNamedPlugins.add(plugin.name);
+        deduped.push(plugin);
+    }
+
+    return deduped;
+}
+
+/**
+ * Configuration options for {@link defineNorthwesternConfig}.
+ *
+ * Extends Astro's config (minus `integrations`) with Northwestern-specific
+ * keys for Starlight, theming, and Mermaid. Integration ordering is handled
+ * automatically. Use the `integrations` escape hatch only when you need
+ * to inject integrations before or after the managed ones.
+ */
+export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> & {
+    /** Full Starlight configuration. Supports all Starlight options with autocompletion. */
+    starlight: StarlightUserConfig;
+
+    /**
+     * Northwestern theme plugin options (hero layout, OG images, etc.).
+     *
+     * @see {@link NorthwesternThemeConfig}
+     */
+    theme?: NorthwesternThemeConfig;
+
+    /**
+     * Mermaid diagram support.
+     *
+     * - `true` (default) — adds `northwesternMermaid()` before `starlight()` with
+     *   default options (branded colors, toolbar, dark mode). Requires `astro-mermaid`
+     *   and `mermaid` to be installed.
+     * - `false` — disable Mermaid entirely
+     * - `object` — adds `northwesternMermaid(options)` before `starlight()` with
+     *   custom options (toolbar, theme overrides, etc.)
+     */
+    mermaid?: boolean | NorthwesternMermaidOptions;
+
+    /**
+     * Additional Starlight plugins to register alongside the Northwestern theme.
+     *
+     * The theme plugin is always first; these are appended after it.
+     */
+    plugins?: StarlightPlugin[];
+
+    /**
+     * Escape hatch for advanced integration ordering.
+     *
+     * - `before` — added before Mermaid and Starlight
+     * - `after` — added after Starlight
+     */
+    integrations?: {
+        before?: AstroIntegration[];
+        after?: AstroIntegration[];
+    };
+};
+
+/**
+ * Create a complete Astro config with Northwestern Starlight theme defaults.
+ *
+ * Handles integration ordering (mermaid → starlight), plugin registration,
+ * and Expressive Code (GitHub themes, line-numbers plugin). The return
+ * value is a standard `AstroUserConfig` ready to
+ * `export default` from `astro.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineNorthwesternConfig } from "@nu-appdev/northwestern-starlight-theme/config";
+ *
+ * export default defineNorthwesternConfig({
+ *     site: "https://docs.example.northwestern.edu",
+ *     starlight: {
+ *         title: "My Docs",
+ *         sidebar: [{ label: "Guide", autogenerate: { directory: "guide" } }],
+ *     },
+ * });
+ * ```
+ */
+export function defineNorthwesternConfig(options: NorthwesternConfigOptions): AstroUserConfig {
+    const validatedOptions = validateSchema(northwesternConfigOptionsSchema, options, "config helper options");
+    const {
+        starlight: starlightConfig,
+        theme,
+        mermaid = true,
+        plugins = [],
+        integrations: extraIntegrations,
+        ...astroConfig
+    } = validatedOptions as NorthwesternConfigOptions;
+
+    const {
+        expressiveCode: userExpressiveCode,
+        plugins: starlightPlugins = [],
+        ...restStarlightConfig
+    } = starlightConfig;
+    const helperPlugins = plugins;
+
+    // Warn if user manually added northwesternTheme in plugins
+    for (const plugin of [...starlightPlugins, ...helperPlugins]) {
+        if (plugin.name === "northwestern-starlight-theme") {
+            console.warn(
+                "[northwestern-starlight-theme] `northwesternTheme()` was found in `plugins` — " +
+                    "the config helper adds it automatically. Remove it from `plugins` to avoid " +
+                    "double-registration. Use the `theme` key for options instead.",
+            );
+        }
+    }
+
+    if (starlightPlugins.length > 0) {
+        console.warn(
+            "[northwestern-starlight-theme] `starlight.plugins` was found in the helper config. Those plugins will be preserved, " +
+                "but the helper's top-level `plugins` key is the preferred API for new configs.",
+        );
+    }
+
+    if (theme?.mermaid !== undefined) {
+        console.warn(
+            "[northwestern-starlight-theme] `theme.mermaid` is ignored by `defineNorthwesternConfig()`. " +
+                "Use the helper's top-level `mermaid` option instead.",
+        );
+    }
+
+    // Build theme config, handling mermaid dual-path.
+    // The standalone northwesternMermaid() integration MUST be added before starlight()
+    // so its remark plugin processes mermaid code blocks before expressive-code.
+    // The theme's built-in mermaid (via addIntegration inside config:setup) runs too late.
+    const themeConfig: NorthwesternThemeConfig = { ...theme };
+    let mermaidIntegration: AstroIntegration | undefined;
+    const hasAstroMermaid = hasOptionalPackage("astro-mermaid");
+    const hasMermaid = hasOptionalPackage("mermaid");
+
+    if (mermaid && (!hasAstroMermaid || !hasMermaid)) {
+        const missingPackages = [
+            ...(!hasAstroMermaid ? ['"astro-mermaid"'] : []),
+            ...(!hasMermaid ? ['"mermaid"'] : []),
+        ];
+        console.warn(
+            `[northwestern-starlight-theme] Mermaid support was requested, but ${missingPackages.join(" and ")} ${
+                missingPackages.length === 1 ? "is" : "are"
+            } not installed. Mermaid integration will be skipped. Install the missing package(s) to enable Mermaid support.`,
+        );
+    }
+
+    if (typeof mermaid === "object" && hasAstroMermaid && hasMermaid) {
+        // Standalone integration with custom options; disable the theme's built-in
+        themeConfig.mermaid = false;
+        mermaidIntegration = northwesternMermaid(mermaid);
+    } else if (mermaid && hasAstroMermaid && hasMermaid) {
+        // Auto-detect: add standalone integration (handles toolbar + dark mode),
+        // disable theme's built-in to prevent double-registration
+        themeConfig.mermaid = false;
+        mermaidIntegration = northwesternMermaid();
+    } else {
+        themeConfig.mermaid = false;
+    }
+
+    // Build Expressive Code config: GitHub themes + line-numbers plugin.
+    // Merge with any user-provided expressiveCode settings.
+    const expressiveCodeConfig: StarlightExpressiveCodeOptions = {
+        plugins: [pluginLineNumbers()],
+        defaultProps: { showLineNumbers: false },
+        themes: ["github-dark", "github-light"],
+        useStarlightUiThemeColors: true,
+        ...(typeof userExpressiveCode === "object" ? userExpressiveCode : {}),
+    };
+    const mergedPlugins = mergeStarlightPlugins(northwesternTheme(themeConfig), starlightPlugins, helperPlugins);
+
+    // Build integration array: before → [mermaid] → starlight → after
+    const integrations: AstroIntegration[] = [
+        ...(extraIntegrations?.before ?? []),
+        ...(mermaidIntegration ? [mermaidIntegration] : []),
+        starlight({
+            ...restStarlightConfig,
+            expressiveCode: expressiveCodeConfig,
+            plugins: mergedPlugins,
+        }),
+        ...(extraIntegrations?.after ?? []),
+    ];
+
+    const existingViteConfig = (astroConfig.vite ?? {}) as {
+        plugins?: unknown | unknown[];
+    };
+    const existingVitePlugins = Array.isArray(existingViteConfig.plugins)
+        ? existingViteConfig.plugins
+        : existingViteConfig.plugins
+          ? [existingViteConfig.plugins]
+          : [];
+
+    return {
+        ...astroConfig,
+        integrations,
+        vite: {
+            ...existingViteConfig,
+            plugins: [...existingVitePlugins, northwesternEcVitePlugin()],
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,82 @@
+import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
+import type { AstroIntegration, AstroUserConfig } from "astro";
+import type { NorthwesternThemeConfig } from "./index";
+import { type NorthwesternMermaidOptions } from "./mermaid";
+/**
+ * Merge helper-managed and migrated Starlight plugins into a stable order.
+ *
+ * The Northwestern theme plugin is always first. Existing `starlight.plugins`
+ * are preserved next for migration compatibility, and helper-level `plugins`
+ * are appended last. Named plugins are deduped by first occurrence.
+ *
+ * @internal
+ */
+export declare function mergeStarlightPlugins(themePlugin: StarlightPlugin, starlightPlugins: StarlightPlugin[], helperPlugins: StarlightPlugin[]): StarlightPlugin[];
+/**
+ * Configuration options for {@link defineNorthwesternConfig}.
+ *
+ * Extends Astro's config (minus `integrations`) with Northwestern-specific
+ * keys for Starlight, theming, and Mermaid. Integration ordering is handled
+ * automatically. Use the `integrations` escape hatch only when you need
+ * to inject integrations before or after the managed ones.
+ */
+export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> & {
+    /** Full Starlight configuration. Supports all Starlight options with autocompletion. */
+    starlight: StarlightUserConfig;
+    /**
+     * Northwestern theme plugin options (hero layout, OG images, etc.).
+     *
+     * @see {@link NorthwesternThemeConfig}
+     */
+    theme?: NorthwesternThemeConfig;
+    /**
+     * Mermaid diagram support.
+     *
+     * - `true` (default) — adds `northwesternMermaid()` before `starlight()` with
+     *   default options (branded colors, toolbar, dark mode). Requires `astro-mermaid`
+     *   and `mermaid` to be installed.
+     * - `false` — disable Mermaid entirely
+     * - `object` — adds `northwesternMermaid(options)` before `starlight()` with
+     *   custom options (toolbar, theme overrides, etc.)
+     */
+    mermaid?: boolean | NorthwesternMermaidOptions;
+    /**
+     * Additional Starlight plugins to register alongside the Northwestern theme.
+     *
+     * The theme plugin is always first; these are appended after it.
+     */
+    plugins?: StarlightPlugin[];
+    /**
+     * Escape hatch for advanced integration ordering.
+     *
+     * - `before` — added before Mermaid and Starlight
+     * - `after` — added after Starlight
+     */
+    integrations?: {
+        before?: AstroIntegration[];
+        after?: AstroIntegration[];
+    };
+};
+/**
+ * Create a complete Astro config with Northwestern Starlight theme defaults.
+ *
+ * Handles integration ordering (mermaid → starlight), plugin registration,
+ * and Expressive Code (GitHub themes, line-numbers plugin). The return
+ * value is a standard `AstroUserConfig` ready to
+ * `export default` from `astro.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineNorthwesternConfig } from "@nu-appdev/northwestern-starlight-theme/config";
+ *
+ * export default defineNorthwesternConfig({
+ *     site: "https://docs.example.northwestern.edu",
+ *     starlight: {
+ *         title: "My Docs",
+ *         sidebar: [{ label: "Guide", autogenerate: { directory: "guide" } }],
+ *     },
+ * });
+ * ```
+ */
+export declare function defineNorthwesternConfig(options: NorthwesternConfigOptions): AstroUserConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAErF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,KAAK,0BAA0B,EAAuB,MAAM,WAAW,CAAC;AA2EjF;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACjC,WAAW,EAAE,eAAe,EAC5B,gBAAgB,EAAE,eAAe,EAAE,EACnC,aAAa,EAAE,eAAe,EAAE,GACjC,eAAe,EAAE,CAmBnB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG;IAC5E,wFAAwF;IACxF,SAAS,EAAE,mBAAmB,CAAC;IAE/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAEhC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,0BAA0B,CAAC;IAE/C;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC5B,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;KAC9B,CAAC;CACL,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,eAAe,CAqH5F"}

package/dist/expressive-code.d.ts

@@ -0,0 +1,21 @@
+import type { StarlightExpressiveCodeOptions } from "@astrojs/starlight/expressive-code";
+/**
+ * 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 declare function northwesternExpressiveCode(config?: StarlightExpressiveCodeOptions): StarlightExpressiveCodeOptions;
+//# sourceMappingURL=expressive-code.d.ts.map

package/dist/expressive-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressive-code.d.ts","sourceRoot":"","sources":["../expressive-code.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AAGzF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,GAAE,8BAAmC,GAC5C,8BAA8B,CAWhC"}

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { StarlightPlugin } from "@astrojs/starlight/types";
+/**
+ * Configuration for the homepage hero section.
+ *
+ * Controls hero layout, title visibility, and image sizing. Passed as the
+ * `homepage` property of {@link NorthwesternThemeConfig}.
+ *
+ * @example
+ * ```ts
+ * northwesternTheme({
+ *     homepage: {
+ *         layout: "split",
+ *         showTitle: false,
+ *         imageWidth: "750px",
+ *     },
+ * })
+ * ```
+ */
+export interface NorthwesternHomepageConfig {
+    /**
+     * Hero layout style.
+     *
+     * - `"centered"` (default) — image above title, everything centered
+     * - `"split"` — text + buttons on the left, image on the right (60/40 split)
+     */
+    layout?: "centered" | "split";
+    /**
+     * Whether to display the page title in the hero.
+     *
+     * Set to `false` when the hero image is a lockup that already contains the title.
+     *
+     * @default true
+     */
+    showTitle?: boolean;
+    /**
+     * Maximum width of the hero image in the centered layout, in pixels.
+     *
+     * Use a larger value for wide lockup images (e.g., `"750px"`, `"1000px"`).
+     *
+     * @default "500px"
+     */
+    imageWidth?: string;
+}
+/**
+ * Top-level configuration for the Northwestern Starlight theme plugin.
+ *
+ * With `defineNorthwesternConfig`, pass these as the `theme` key.
+ * With `northwesternTheme()` directly, pass them as the function argument.
+ * All properties are optional.
+ *
+ * @example
+ * ```ts
+ * defineNorthwesternConfig({
+ *     starlight: { title: "My Docs" },
+ *     theme: { homepage: { layout: "split" } },
+ * })
+ * ```
+ *
+ * @see {@link NorthwesternHomepageConfig} for homepage hero options
+ */
+export interface NorthwesternThemeConfig {
+    /**
+     * Homepage hero layout configuration.
+     *
+     * @see {@link NorthwesternHomepageConfig}
+     */
+    homepage?: NorthwesternHomepageConfig;
+    /**
+     * Mermaid diagram support.
+     *
+     * - `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 Mermaid config merged with Northwestern defaults
+     *
+     * @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;
+}
+/**
+ * Create a Northwestern-branded Starlight theme plugin.
+ *
+ * Registers Northwestern typography (Akkurat Pro, Poppins), purple color palette,
+ * 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 Manual setup
+ * ```ts
+ * starlight({ plugins: [northwesternTheme()] })
+ * ```
+ *
+ * @example Split hero with Mermaid disabled
+ * ```ts
+ * starlight({
+ *     plugins: [
+ *         northwesternTheme({
+ *             homepage: { layout: "split", showTitle: false },
+ *             mermaid: false,
+ *         }),
+ *     ],
+ * })
+ * ```
+ */
+export default function northwesternTheme(config?: NorthwesternThemeConfig): StarlightPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAIhE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,uBAAuB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IAEtC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,MAAM,GAAE,uBAA4B,GAAG,eAAe,CAkP/F"}