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

package/legacy-html-redirects.ts

@@ -0,0 +1,168 @@
+import { readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from "node:fs";
+import { join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AstroIntegration } from "astro";
+import { legacyHtmlRedirectsOptionsSchema, validateSchema } from "./src/config-schema";
+
+/**
+ * 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;
+}
+
+const DEFAULT_CONTENT_DIR = "src/content/docs";
+const MARKDOWN_EXTENSION = /\.(md|mdx)$/;
+const INDEX_SUFFIX = "/index";
+// Slugs Astro emits as flat `.html` files rather than `<slug>/index.html`.
+// Generating a directory-form redirect at the same path collides with Astro's
+// own write during the build. The `404` page is the one documented case.
+const RESERVED_SLUGS = new Set(["404"]);
+
+/**
+ * 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 function generateLegacyHtmlRedirects(options: LegacyHtmlRedirectsOptions = {}): Record<string, string> {
+    const { contentDir = DEFAULT_CONTENT_DIR } = validateSchema(
+        legacyHtmlRedirectsOptionsSchema,
+        options,
+        "legacyHtmlRedirects options",
+    );
+
+    const redirects: Record<string, string> = {};
+
+    for (const entry of readdirSync(contentDir, { recursive: true }) as string[]) {
+        if (!MARKDOWN_EXTENSION.test(entry)) continue;
+
+        const slug = entry.split(sep).join("/").replace(MARKDOWN_EXTENSION, "");
+        if (slug === "index") continue;
+
+        const canonical = slug.endsWith(INDEX_SUFFIX) ? slug.slice(0, -INDEX_SUFFIX.length) : slug;
+        if (RESERVED_SLUGS.has(canonical)) continue;
+        redirects[`/${canonical}.html`] = `/${canonical}/`;
+    }
+
+    return redirects;
+}
+
+/**
+ * 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 function legacyHtmlRedirectsIntegration(): AstroIntegration {
+    return {
+        name: "northwestern-legacy-html-redirects",
+        hooks: {
+            "astro:build:done": ({ dir }) => {
+                flattenHtmlRedirectDirs(fileURLToPath(dir));
+            },
+        },
+    };
+}
+
+/** @internal — exposed for unit tests. */
+export function flattenHtmlRedirectDirs(distDir: string): void {
+    walk(distDir, ".");
+}
+
+function walk(root: string, rel: string): void {
+    for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+
+        const childRel = join(rel, entry.name);
+        if (entry.name.endsWith(".html")) {
+            flattenOne(root, childRel);
+        } else {
+            walk(root, childRel);
+        }
+    }
+}
+
+// Collapse `<root>/<rel>/index.html` → `<root>/<rel>` (a flat file), rewriting
+// the redirect page so the URL hash survives the forward. Skips directories
+// that don't look like an Astro-emitted redirect page (i.e. contain anything
+// besides a single `index.html`) so unrelated `.html`-named directories are
+// left alone.
+function flattenOne(root: string, rel: string): void {
+    const dirPath = join(root, rel);
+    const contents = readdirSync(dirPath);
+    if (contents.length !== 1 || contents[0] !== "index.html") return;
+
+    const indexPath = join(dirPath, "index.html");
+    const rewritten = rewriteRedirectPage(readFileSync(indexPath, "utf8"));
+    writeFileSync(indexPath, rewritten);
+
+    const tmpPath = join(root, `${rel}.__tmp`);
+    renameSync(indexPath, tmpPath);
+    rmdirSync(dirPath);
+    renameSync(tmpPath, dirPath);
+}
+
+const META_REFRESH_TAG = /<meta\s+http-equiv="refresh"[^>]*>/i;
+const META_REFRESH_URL = /url=([^"]+)"/i;
+const HASH_FORWARD_SCRIPT = /<script>location\.replace\(/;
+
+/**
+ * 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 function rewriteRedirectPage(html: string): string {
+    if (HASH_FORWARD_SCRIPT.test(html)) return html;
+
+    const metaRefresh = html.match(META_REFRESH_TAG)?.[0];
+    if (!metaRefresh) return html;
+
+    const target = metaRefresh.match(META_REFRESH_URL)?.[1];
+    if (!target) return html;
+
+    const script = `<script>location.replace(${JSON.stringify(target)}+location.hash);</script>`;
+    return html.replace(metaRefresh, `${script}<noscript>${metaRefresh}</noscript>`);
+}

package/mermaid.ts

@@ -1,6 +1,7 @@
 import type { AstroIntegration } from "astro";
-import mermaid, { type AstroMermaidOptions } from "astro-mermaid";
+import type { AstroMermaidOptions } from "astro-mermaid";
 import { darken, isDark, lighten, mix, transparentize } from "khroma";
+import { northwesternMermaidOptionsSchema, validateSchema } from "./src/config-schema";
 
 /**
  * Configuration options for the Northwestern Mermaid integration.
@@ -417,6 +418,9 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  * 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
@@ -426,7 +430,7 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  *   disable the hover toolbar.
  * @returns An Astro integration to add to `integrations` in your Astro config.
  *
- * @example
+ * @example Manual setup
  * ```ts
  * import { northwesternMermaid } from "@nu-appdev/northwestern-starlight-theme/mermaid";
  * import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
@@ -443,7 +447,11 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  * ```
  */
 export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): AstroIntegration {
-    const { toolbar = true, ...overrides } = options;
+    const { toolbar = true, ...overrides } = validateSchema(
+        northwesternMermaidOptionsSchema,
+        options,
+        "Mermaid config",
+    );
     const lightConfig = createNorthwesternMermaidConfig("light");
     const darkConfig = createNorthwesternMermaidConfig("dark");
 
@@ -463,19 +471,21 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
 
     const mergedLightMermaidConfig = mergeWithOverrides(lightConfig.mermaidConfig as Record<string, unknown>);
     const mergedDarkMermaidConfig = mergeWithOverrides(darkConfig.mermaidConfig as Record<string, unknown>);
-
-    const mermaidIntegration = mermaid({
-        ...lightConfig,
-        ...overrides,
-        enableLog: false,
-        mermaidConfig: mergedLightMermaidConfig,
-    });
+    const mermaidModulePromise = import("astro-mermaid");
 
     return {
         name: "northwestern-mermaid",
         hooks: {
-            "astro:config:setup"(params) {
-                mermaidIntegration.hooks["astro:config:setup"]?.(params);
+            async "astro:config:setup"(params) {
+                const { default: mermaid } = await mermaidModulePromise;
+                const mermaidIntegration = mermaid({
+                    ...lightConfig,
+                    ...overrides,
+                    enableLog: false,
+                    mermaidConfig: mergedLightMermaidConfig,
+                });
+
+                await mermaidIntegration.hooks["astro:config:setup"]?.(params);
 
                 params.injectScript(
                     "page",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -28,16 +28,25 @@
   },
   "exports": {
     ".": {
-      "types": "./index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./index.ts"
     },
     "./expressive-code": {
-      "import": "./expressive-code.mjs"
+      "types": "./dist/expressive-code.d.ts",
+      "import": "./expressive-code.ts"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./config.ts"
     },
     "./mermaid": {
-      "types": "./mermaid.ts",
+      "types": "./dist/mermaid.d.ts",
       "import": "./mermaid.ts"
     },
+    "./legacy-html-redirects": {
+      "types": "./dist/legacy-html-redirects.d.ts",
+      "import": "./legacy-html-redirects.ts"
+    },
     "./components": {
       "types": "./src/components/index.ts",
       "import": "./src/components/index.ts"
@@ -50,15 +59,20 @@
   },
   "files": [
     "CHANGELOG.md",
-    "expressive-code.mjs",
+    "dist/",
+    "config.ts",
+    "expressive-code.ts",
     "index.ts",
+    "legacy-html-redirects.ts",
     "mermaid.ts",
     "src/"
   ],
   "dependencies": {
     "@expressive-code/plugin-line-numbers": "^0.41.7",
-    "astro-og-canvas": "^0.10.1",
-    "khroma": "^2.1.0"
+    "@resvg/resvg-wasm": "^2.6.2",
+    "khroma": "^2.1.0",
+    "satori": "^0.26.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.32.0",
@@ -75,6 +89,10 @@
     }
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4"
+    "@types/hast": "^3.0.4",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --noCheck"
   }
 }

package/src/config-schema.ts

@@ -0,0 +1,285 @@
+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.",
+    });
+
+/**
+ * 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 const legacyHtmlRedirectsOptionsSchema = z
+    .strictObject({
+        contentDir: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .meta({
+                description: "Project-relative path to the Markdown/MDX content root.",
+                examples: ["src/content/docs"],
+            }),
+    })
+    .meta({
+        description: "Options for the legacy .html redirect generator.",
+    });
+
+/**
+ * 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.",
+        }),
+
+        /**
+         * 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.union([z.boolean(), legacyHtmlRedirectsOptionsSchema]).optional().meta({
+            description:
+                "Opt-in helper that generates .html → canonical redirects for sites migrated from VuePress (or any .html-extension source), and patches the redirect pages so URL hashes survive the forward.",
+        }),
+
+        /**
+         * 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;
+}