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

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-04-22
+
+### Added
+
+- **Legacy `.html` redirects.** Sites migrated from VuePress had every page served at `<slug>.html`; external bookmarks and inbound links still point there. A new `legacyHtmlRedirects` option on `defineNorthwesternConfig` (default `true`) scans `src/content/docs` and emits a redirect from `<slug>.html` to the canonical `<slug>/` URL for every page, with the URL hash preserved on forward so deep links like `#schedule-management` still land on the right anchor.
+
 ## [1.5.0] - 2026-03-31
 
 ### Added
@@ -179,7 +185,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.5.0...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.0...v1.5.1
 [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

package/config.ts

@@ -8,6 +8,11 @@ import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 import type { AstroIntegration, AstroUserConfig } from "astro";
 import type { NorthwesternThemeConfig } from "./index";
 import northwesternTheme from "./index";
+import {
+    generateLegacyHtmlRedirects,
+    type LegacyHtmlRedirectsOptions,
+    legacyHtmlRedirectsIntegration,
+} from "./legacy-html-redirects";
 import { type NorthwesternMermaidOptions, northwesternMermaid } from "./mermaid";
 import { northwesternConfigOptionsSchema, validateSchema } from "./src/config-schema";
 
@@ -155,6 +160,23 @@ export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> &
      */
     plugins?: StarlightPlugin[];
 
+    /**
+     * Generate `.html` redirects for sites migrated from VuePress (or any
+     * `.html`-extension source) and patch the emitted redirect pages so
+     * deep-link hash fragments survive the forward.
+     *
+     * - `true` (default) — scan `src/content/docs`
+     * - `false` — do nothing
+     * - `object` — scan a custom content directory
+     *
+     * Generated redirects are merged with any `redirects` already on this
+     * config; user-specified redirects win on conflicts.
+     *
+     * @default true
+     * @see {@link LegacyHtmlRedirectsOptions}
+     */
+    legacyHtmlRedirects?: boolean | LegacyHtmlRedirectsOptions;
+
     /**
      * Escape hatch for advanced integration ordering.
      *
@@ -196,6 +218,7 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
         mermaid = true,
         plugins = [],
         integrations: extraIntegrations,
+        legacyHtmlRedirects = true,
         ...astroConfig
     } = validatedOptions as NorthwesternConfigOptions;
 
@@ -276,7 +299,9 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     };
     const mergedPlugins = mergeStarlightPlugins(northwesternTheme(themeConfig), starlightPlugins, helperPlugins);
 
-    // Build integration array: before → [mermaid] → starlight → after
+    // Build integration array: before → [mermaid] → starlight → after → [legacy-html-redirects]
+    // The legacy-html-redirects integration runs last so it rewrites redirect pages
+    // after every other astro:build:done hook has had a chance to emit them.
     const integrations: AstroIntegration[] = [
         ...(extraIntegrations?.before ?? []),
         ...(mermaidIntegration ? [mermaidIntegration] : []),
@@ -286,8 +311,17 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
             plugins: mergedPlugins,
         }),
         ...(extraIntegrations?.after ?? []),
+        ...(legacyHtmlRedirects ? [legacyHtmlRedirectsIntegration()] : []),
     ];
 
+    const generatedHtmlRedirects = legacyHtmlRedirects
+        ? generateLegacyHtmlRedirects(typeof legacyHtmlRedirects === "object" ? legacyHtmlRedirects : undefined)
+        : undefined;
+    // User-specified redirects take precedence when keys overlap.
+    const mergedRedirects = generatedHtmlRedirects
+        ? { ...generatedHtmlRedirects, ...(astroConfig.redirects ?? {}) }
+        : astroConfig.redirects;
+
     const existingViteConfig = (astroConfig.vite ?? {}) as {
         plugins?: unknown | unknown[];
     };
@@ -300,6 +334,7 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     return {
         ...astroConfig,
         integrations,
+        ...(mergedRedirects ? { redirects: mergedRedirects } : {}),
         vite: {
             ...existingViteConfig,
             plugins: [...existingVitePlugins, northwesternEcVitePlugin()],

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
 import type { AstroIntegration, AstroUserConfig } from "astro";
 import type { NorthwesternThemeConfig } from "./index";
+import { type LegacyHtmlRedirectsOptions } from "./legacy-html-redirects";
 import { type NorthwesternMermaidOptions } from "./mermaid";
 /**
  * Merge helper-managed and migrated Starlight plugins into a stable order.
@@ -46,6 +47,22 @@ export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> &
      * The theme plugin is always first; these are appended after it.
      */
     plugins?: StarlightPlugin[];
+    /**
+     * Generate `.html` redirects for sites migrated from VuePress (or any
+     * `.html`-extension source) and patch the emitted redirect pages so
+     * deep-link hash fragments survive the forward.
+     *
+     * - `true` (default) — scan `src/content/docs`
+     * - `false` — do nothing
+     * - `object` — scan a custom content directory
+     *
+     * Generated redirects are merged with any `redirects` already on this
+     * config; user-specified redirects win on conflicts.
+     *
+     * @default true
+     * @see {@link LegacyHtmlRedirectsOptions}
+     */
+    legacyHtmlRedirects?: boolean | LegacyHtmlRedirectsOptions;
     /**
      * Escape hatch for advanced integration ordering.
      *

package/dist/config.d.ts.map

@@ -1 +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"}
+{"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,EAEH,KAAK,0BAA0B,EAElC,MAAM,yBAAyB,CAAC;AACjC,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;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,0BAA0B,CAAC;IAE3D;;;;;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,CAkI5F"}

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/src/config-schema.d.ts

@@ -53,6 +53,15 @@ export declare const northwesternMermaidOptionsSchema: z.ZodObject<{
      */
     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()`.
  *
@@ -117,6 +126,17 @@ export declare const northwesternConfigOptionsSchema: z.ZodObject<{
      * 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.
      *

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

@@ -1 +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,+BAA+B;IAEpC;;;;;OAKG;;IAKH;;OAEG;;QA9EH;;WAEG;;;;;;;;;QAKH;;;;;;WAMG;;QASH;;;;;WAKG;;;IAwDH;;;;;;OAMG;;QA7CH;;;;WAIG;;;IA+CH;;OAEG;;IAKH;;;;;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"}
+{"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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -43,6 +43,10 @@
       "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"
@@ -59,6 +63,7 @@
     "config.ts",
     "expressive-code.ts",
     "index.ts",
+    "legacy-html-redirects.ts",
     "mermaid.ts",
     "src/"
   ],

package/src/config-schema.ts

@@ -136,6 +136,28 @@ export const northwesternMermaidOptionsSchema = z
             "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()`.
  *
@@ -180,6 +202,19 @@ export const northwesternConfigOptionsSchema = z
             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.
          *