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

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-07-28
+
+### Added
+
+- Fullscreen Mermaid diagrams can be downloaded as high-resolution PNG files. PNG exports render at up to 4× the diagram's intrinsic size, use the active Mermaid theme's configured canvas color for reliable contrast, and share the same descriptive filenames as SVG downloads.
+
+## [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 +191,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI plugin compatibility with method badge preservation
 - Reduced motion support for transitions
 
-[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.1...v1.6.0
+[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/README.md

@@ -5,7 +5,7 @@
 
 <p align="center">
     <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22+-339933?style=flat&logo=node.js&logoColor=white" alt="Node Version"></a>
-    <a href="https://astro.build"><img src="https://img.shields.io/badge/Astro-5.x%20%7C%206.x-BC52EE?style=flat&logo=astro&logoColor=white" alt="Astro Version"></a>
+    <a href="https://astro.build"><img src="https://img.shields.io/badge/Astro-5.x%20%7C%206.x%20%7C%207.x-BC52EE?style=flat&logo=astro&logoColor=white" alt="Astro Version"></a>
     <a href="https://starlight.astro.build"><img src="https://img.shields.io/badge/Starlight-0.32+-FF5D01?style=flat&logo=astro&logoColor=white" alt="Starlight Version"></a>
 </p>
 

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";
 
@@ -139,11 +144,11 @@ export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> &
     /**
      * Mermaid diagram support.
      *
-     * - `true` (default) — adds `northwesternMermaid()` before `starlight()` with
+     * - `true` (default) — adds `northwesternMermaid()` after `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
+     * - `object` — adds `northwesternMermaid(options)` after `starlight()` with
      *   custom options (toolbar, theme overrides, etc.)
      */
     mermaid?: boolean | NorthwesternMermaidOptions;
@@ -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;
 
@@ -232,9 +255,8 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     }
 
     // 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.
+    // astro-mermaid 2.1 detects Starlight's active Markdown processor, so the
+    // standalone integration is added immediately after Starlight below.
     const themeConfig: NorthwesternThemeConfig = { ...theme };
     let mermaidIntegration: AstroIntegration | undefined;
     const hasAstroMermaid = hasOptionalPackage("astro-mermaid");
@@ -276,18 +298,29 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     };
     const mergedPlugins = mergeStarlightPlugins(northwesternTheme(themeConfig), starlightPlugins, helperPlugins);
 
-    // Build integration array: before → [mermaid] → starlight → after
+    // Build integration array: before → starlight → [mermaid] → 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] : []),
         starlight({
             ...restStarlightConfig,
             expressiveCode: expressiveCodeConfig,
             plugins: mergedPlugins,
         }),
+        ...(mermaidIntegration ? [mermaidIntegration] : []),
         ...(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 +333,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.
@@ -32,11 +33,11 @@ export type NorthwesternConfigOptions = Omit<AstroUserConfig, "integrations"> &
     /**
      * Mermaid diagram support.
      *
-     * - `true` (default) — adds `northwesternMermaid()` before `starlight()` with
+     * - `true` (default) — adds `northwesternMermaid()` after `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
+     * - `object` — adds `northwesternMermaid(options)` after `starlight()` with
      *   custom options (toolbar, theme overrides, etc.)
      */
     mermaid?: boolean | NorthwesternMermaidOptions;
@@ -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,CAiI5F"}

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAMA,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,CAgQ/F"}

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

@@ -68,10 +68,9 @@ export declare const darkMermaidConfig: AstroMermaidOptions;
  * **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.
+ * **Must be added after `starlight()` in the `integrations` array.** This lets
+ * `astro-mermaid` detect and extend Starlight's active Markdown processor,
+ * including Astro 7's Sätteri pipeline.
  *
  * @param options - Merged with Northwestern defaults. Set `toolbar: false` to
  *   disable the hover toolbar.
@@ -84,11 +83,11 @@ export declare const darkMermaidConfig: AstroMermaidOptions;
  *
  * export default defineConfig({
  *     integrations: [
- *         northwesternMermaid(), // Must come before starlight()
  *         starlight({
  *             plugins: [northwesternTheme()],
  *             title: "My Docs",
  *         }),
+ *         northwesternMermaid(), // Must come after starlight()
  *     ],
  * });
  * ```

package/dist/mermaid.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../mermaid.ts"],"names":[],"mappings":"AACA,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,gBAAgB,CA+E9F"}

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

@@ -12,9 +12,6 @@ export declare const nonEmptyStringSchema: z.ZodString;
  * 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";
@@ -23,20 +20,7 @@ export declare const northwesternThemeConfigSchema: z.ZodObject<{
         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>;
 /**
@@ -46,13 +30,17 @@ export declare const northwesternThemeConfigSchema: z.ZodObject<{
  * 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()`.
  *
@@ -60,20 +48,8 @@ export declare const northwesternMermaidOptionsSchema: z.ZodObject<{
  * 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";
@@ -82,55 +58,18 @@ export declare const northwesternConfigOptionsSchema: z.ZodObject<{
             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>>;
-    /**
-     * 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.
-     */
+    legacyHtmlRedirects: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        contentDir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
     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>;

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;;;;;;;;;;;kBAoCpC,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC;;iBAcvC,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC;;kBAcvC,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;iBAgFtC,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.map

@@ -1 +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"}
+{"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,WACvB,IAAI,UACrB"}

package/index.ts

@@ -3,6 +3,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { unified } from "@astrojs/markdown-remark";
 import type { StarlightPlugin } from "@astrojs/starlight/types";
 import { nonEmptyStringSchema, northwesternThemeConfigSchema, validateSchema } from "./src/config-schema";
 import rehypeTableScroll from "./src/rehype-table-scroll";
@@ -202,11 +203,25 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                 addIntegration({
                     name: "northwestern-theme-config",
                     hooks: {
-                        "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
+                        "astro:config:setup": ({ config: astroConfig, updateConfig: updateAstroConfig }) => {
+                            const markdown = astroConfig.markdown ?? {};
+                            const markdownConfig =
+                                markdown.processor?.name === "satteri"
+                                    ? {
+                                          processor: unified({
+                                              remarkPlugins: markdown.remarkPlugins,
+                                              rehypePlugins: [...(markdown.rehypePlugins ?? []), rehypeTableScroll],
+                                              remarkRehype: markdown.remarkRehype,
+                                              gfm: markdown.gfm,
+                                              smartypants: markdown.smartypants,
+                                          }),
+                                      }
+                                    : {
+                                          rehypePlugins: [...(markdown.rehypePlugins ?? []), rehypeTableScroll],
+                                      };
+
                             updateAstroConfig({
-                                markdown: {
-                                    rehypePlugins: [rehypeTableScroll],
-                                },
+                                markdown: markdownConfig,
                                 vite: {
                                     plugins: [
                                         {

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,3 +1,4 @@
+import { unified } from "@astrojs/markdown-remark";
 import type { AstroIntegration } from "astro";
 import type { AstroMermaidOptions } from "astro-mermaid";
 import { darken, isDark, lighten, mix, transparentize } from "khroma";
@@ -421,10 +422,9 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  * **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.
+ * **Must be added after `starlight()` in the `integrations` array.** This lets
+ * `astro-mermaid` detect and extend Starlight's active Markdown processor,
+ * including Astro 7's Sätteri pipeline.
  *
  * @param options - Merged with Northwestern defaults. Set `toolbar: false` to
  *   disable the hover toolbar.
@@ -437,11 +437,11 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  *
  * export default defineConfig({
  *     integrations: [
- *         northwesternMermaid(), // Must come before starlight()
  *         starlight({
  *             plugins: [northwesternTheme()],
  *             title: "My Docs",
  *         }),
+ *         northwesternMermaid(), // Must come after starlight()
  *     ],
  * });
  * ```
@@ -478,6 +478,32 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
         hooks: {
             async "astro:config:setup"(params) {
                 const { default: mermaid } = await mermaidModulePromise;
+                let mermaidHookParams = params;
+                const markdown = params.config.markdown ?? {};
+
+                if (markdown.processor?.name === "satteri") {
+                    const processor = unified({
+                        remarkPlugins: markdown.remarkPlugins,
+                        rehypePlugins: markdown.rehypePlugins,
+                        remarkRehype: markdown.remarkRehype,
+                        gfm: markdown.gfm,
+                        smartypants: markdown.smartypants,
+                    });
+                    const unifiedMarkdown = {
+                        ...markdown,
+                        processor,
+                    };
+
+                    params.updateConfig({ markdown: { processor } });
+                    mermaidHookParams = {
+                        ...params,
+                        config: {
+                            ...params.config,
+                            markdown: unifiedMarkdown,
+                        },
+                    };
+                }
+
                 const mermaidIntegration = mermaid({
                     ...lightConfig,
                     ...overrides,
@@ -485,7 +511,7 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
                     mermaidConfig: mergedLightMermaidConfig,
                 });
 
-                await mermaidIntegration.hooks["astro:config:setup"]?.(params);
+                await mermaidIntegration.hooks["astro:config:setup"]?.(mermaidHookParams);
 
                 params.injectScript(
                     "page",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "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,15 +63,17 @@
     "config.ts",
     "expressive-code.ts",
     "index.ts",
+    "legacy-html-redirects.ts",
     "mermaid.ts",
     "src/"
   ],
   "dependencies": {
-    "@expressive-code/plugin-line-numbers": "^0.41.7",
+    "@astrojs/markdown-remark": "^7.2.2",
+    "@expressive-code/plugin-line-numbers": "^0.44.1",
     "@resvg/resvg-wasm": "^2.6.2",
     "khroma": "^2.1.0",
-    "satori": "^0.26.0",
-    "zod": "^4.3.6"
+    "satori": "^0.29.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.32.0",
@@ -84,8 +90,8 @@
     }
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4",
-    "typescript": "^6.0.2"
+    "@types/hast": "^3.0.5",
+    "typescript": "^7.0.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json --noCheck"

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.
          *

package/src/scripts/mermaid/fullscreen.ts

@@ -9,7 +9,7 @@
 import { installKeyboardAndFocus } from "./focus";
 import { buildOverlay } from "./overlay";
 import { createPanZoomController } from "./pan-zoom";
-import { downloadDiagramSvg, flashSuccess, showToast, writeToClipboard } from "./ui";
+import { downloadDiagramPng, downloadDiagramSvg, flashSuccess, showToast, writeToClipboard } from "./ui";
 
 const OPEN_SCALE = "scale(0.97)";
 const OPEN_TRANSITION = "transform 300ms cubic-bezier(0.16, 1, 0.3, 1)";
@@ -74,6 +74,27 @@ export function openFullscreen(
                 downloadDiagramSvg(diagramSvg, diagramContainer);
                 flashSuccess(button, "Downloaded!");
                 break;
+            case "download-png": {
+                const originalTitle = button.title;
+                button.disabled = true;
+                button.title = "Generating PNG…";
+                button.setAttribute("aria-busy", "true");
+
+                void downloadDiagramPng(diagramSvg, diagramContainer)
+                    .then(() => {
+                        button.title = originalTitle;
+                        flashSuccess(button, "Downloaded!");
+                    })
+                    .catch(() => {
+                        button.title = originalTitle;
+                        showToast(viewport, "PNG download failed");
+                    })
+                    .finally(() => {
+                        button.disabled = false;
+                        button.removeAttribute("aria-busy");
+                    });
+                break;
+            }
             case "copy-svg":
                 writeToClipboard(diagramSvg.outerHTML, button);
                 showToast(viewport, "SVG copied to clipboard");

package/src/scripts/mermaid/overlay.ts

@@ -72,6 +72,9 @@ function buildControlsBar(diagramContainer: HTMLElement) {
     bar.appendChild(separator);
 
     bar.appendChild(createActionButton("Download SVG", "download-svg", ICON_PATHS.download, OVERLAY_BTN_CLASS));
+    bar.appendChild(
+        createActionButton("Download high-resolution PNG", "download-png", ICON_PATHS.image, OVERLAY_BTN_CLASS),
+    );
     bar.appendChild(createActionButton("Copy SVG", "copy-svg", ICON_PATHS.copy, OVERLAY_BTN_CLASS));
 
     const diagramSource = diagramSources.get(diagramContainer);

package/src/scripts/mermaid/ui.ts

@@ -24,6 +24,7 @@ export const ICON_PATHS = {
         "M8 4H6a2 2 0 00-2 2v12a2 2 0 002 2h8a2 2 0 002-2v-2",
         "M16 4h2a2 2 0 012 2v6a2 2 0 01-2 2h-8a2 2 0 01-2-2V6a2 2 0 012-2",
     ],
+    image: ["M3 5a2 2 0 012-2h14a2 2 0 012 2v14a2 2 0 01-2 2H5a2 2 0 01-2-2V5z", "M8.5 8.5h.01", "M21 15l-5-5L5 21"],
     code: ["M16 18l6-6-6-6", "M8 6l-6 6 6 6"],
     check: ["M20 6L9 17l-5-5"],
 } as const;
@@ -210,6 +211,20 @@ export async function writeToClipboard(text: string, triggerButton: HTMLButtonEl
 // SVG download
 // ---------------------------------------------------------------------------
 
+type DownloadExtension = "png" | "svg";
+
+function downloadBlob(blob: Blob, filename: string): void {
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    anchor.hidden = true;
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
 /**
  * Download the diagram SVG with a descriptive filename derived from
  * the site title, page slug, and diagram type.
@@ -218,12 +233,171 @@ export function downloadDiagramSvg(svg: SVGElement, container: Element): void {
     const clone = svg.cloneNode(true) as SVGElement;
     clone.setAttribute("xmlns", SVG_NS);
     const blob = new Blob([clone.outerHTML], { type: "image/svg+xml" });
-    const url = URL.createObjectURL(blob);
-    const anchor = document.createElement("a");
-    anchor.href = url;
-    anchor.download = buildDownloadFilename(container);
-    anchor.click();
-    URL.revokeObjectURL(url);
+    downloadBlob(blob, buildDownloadFilename(container, "svg"));
+}
+
+// ---------------------------------------------------------------------------
+// PNG download
+// ---------------------------------------------------------------------------
+
+const PNG_TARGET_SCALE = 4;
+const MAX_CANVAS_DIMENSION = 8192;
+const MAX_CANVAS_AREA = 16_000_000;
+
+const RASTER_STYLE_PROPERTIES = [
+    "background-color",
+    "border-color",
+    "border-style",
+    "border-width",
+    "color",
+    "display",
+    "dominant-baseline",
+    "fill",
+    "fill-opacity",
+    "fill-rule",
+    "font-family",
+    "font-size",
+    "font-style",
+    "font-weight",
+    "letter-spacing",
+    "line-height",
+    "opacity",
+    "overflow",
+    "paint-order",
+    "shape-rendering",
+    "stroke",
+    "stroke-dasharray",
+    "stroke-dashoffset",
+    "stroke-linecap",
+    "stroke-linejoin",
+    "stroke-miterlimit",
+    "stroke-opacity",
+    "stroke-width",
+    "text-align",
+    "text-anchor",
+    "text-decoration",
+    "text-rendering",
+    "visibility",
+    "white-space",
+    "word-spacing",
+] as const;
+
+function parseSvgDimensions(svg: SVGElement): { width: number; height: number } {
+    const viewBox = svg.getAttribute("viewBox");
+    if (viewBox) {
+        const [, , width, height] = viewBox.split(/[\s,]+/).map(Number);
+        if (width > 0 && height > 0) return { width, height };
+    }
+
+    const bounds = svg.getBoundingClientRect();
+    return {
+        width: bounds.width > 0 ? bounds.width : 800,
+        height: bounds.height > 0 ? bounds.height : 600,
+    };
+}
+
+function calculatePngScale(width: number, height: number): number {
+    return Math.min(
+        PNG_TARGET_SCALE,
+        MAX_CANVAS_DIMENSION / width,
+        MAX_CANVAS_DIMENSION / height,
+        Math.sqrt(MAX_CANVAS_AREA / (width * height)),
+    );
+}
+
+function inlineRasterStyles(source: SVGElement, clone: SVGElement): void {
+    const sourceElements = [source, ...source.querySelectorAll("*")];
+    const cloneElements = [clone, ...clone.querySelectorAll("*")];
+
+    sourceElements.forEach((sourceElement, index) => {
+        const cloneElement = cloneElements[index] as SVGElement | HTMLElement | undefined;
+        if (!cloneElement || !("style" in cloneElement)) return;
+
+        const computedStyle = getComputedStyle(sourceElement);
+        for (const property of RASTER_STYLE_PROPERTIES) {
+            const value = computedStyle.getPropertyValue(property);
+            if (value) cloneElement.style.setProperty(property, value);
+        }
+    });
+}
+
+function isTransparentColor(color: string): boolean {
+    return color === "transparent" || /,\s*0(?:\.0+)?\s*\)$/.test(color) || /\/\s*0(?:\.0+)?%?\s*\)$/.test(color);
+}
+
+function resolveMermaidCanvasColor(): string {
+    const mode = document.documentElement.dataset.theme === "light" ? "light" : "dark";
+    const fallback = mode === "light" ? "#fff" : "#1c1c1f";
+    const themeVariables = window.__NU_MERMAID_CONFIGS__?.[mode]?.themeVariables;
+    const configuredBackground =
+        typeof themeVariables === "object" && themeVariables !== null
+            ? (themeVariables as Record<string, unknown>).background
+            : undefined;
+
+    if (typeof configuredBackground === "string") {
+        const probe = document.createElement("canvas").getContext("2d");
+        if (probe) {
+            probe.fillStyle = fallback;
+            probe.fillStyle = configuredBackground;
+            if (!isTransparentColor(probe.fillStyle)) return probe.fillStyle;
+        }
+    }
+
+    return fallback;
+}
+
+function canvasToPngBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (blob) {
+                resolve(blob);
+            } else {
+                reject(new Error("The browser could not encode the Mermaid diagram as PNG."));
+            }
+        }, "image/png");
+    });
+}
+
+/**
+ * Download a high-resolution PNG of the diagram.
+ *
+ * The raster target is 4× the SVG viewBox (capped to browser-safe canvas
+ * dimensions). The canvas is filled with the active Mermaid theme's configured
+ * background so every exported color keeps its intended contrast.
+ */
+export async function downloadDiagramPng(svg: SVGElement, container: Element): Promise<void> {
+    const { width, height } = parseSvgDimensions(svg);
+    const scale = calculatePngScale(width, height);
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(width * scale));
+    canvas.height = Math.max(1, Math.round(height * scale));
+
+    const context = canvas.getContext("2d", { alpha: false });
+    if (!context) throw new Error("The browser could not create a canvas for the Mermaid diagram.");
+
+    const clone = svg.cloneNode(true) as SVGElement;
+    clone.setAttribute("xmlns", SVG_NS);
+    clone.setAttribute("width", String(width));
+    clone.setAttribute("height", String(height));
+    clone.removeAttribute("style");
+    inlineRasterStyles(svg, clone);
+
+    const serializedSvg = new XMLSerializer().serializeToString(clone);
+    const svgUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(serializedSvg)}`;
+    const image = new Image();
+
+    await new Promise<void>((resolve, reject) => {
+        image.onload = () => resolve();
+        image.onerror = () => reject(new Error("The Mermaid diagram could not be rasterized."));
+        image.src = svgUrl;
+    });
+
+    context.fillStyle = resolveMermaidCanvasColor();
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+
+    const pngBlob = await canvasToPngBlob(canvas);
+    downloadBlob(pngBlob, buildDownloadFilename(container, "png"));
 }
 
 // ---------------------------------------------------------------------------
@@ -252,7 +426,7 @@ function detectDiagramType(container: Element): string {
     return slugify(keyword.replace(/[-_](v\d+|beta)$/i, "").replace(/(diagram|chart)$/i, "")) || "diagram";
 }
 
-function buildDownloadFilename(container: Element): string {
+function buildDownloadFilename(container: Element, extension: DownloadExtension): string {
     const site = extractSiteSlug();
     const page = extractPageSlug();
     const type = detectDiagramType(container);
@@ -261,5 +435,5 @@ function buildDownloadFilename(container: Element): string {
     const sameType = allDiagrams.filter((d) => detectDiagramType(d) === type);
     const disambiguator = sameType.length > 1 ? `-${sameType.indexOf(container as HTMLElement) + 1}` : "";
 
-    return `${site}_${page}-${type}${disambiguator}.svg`;
+    return `${site}_${page}-${type}${disambiguator}.${extension}`;
 }

package/src/styles/mermaid-toolbar.css

@@ -80,6 +80,11 @@
         background: var(--nu-hover-bg);
     }
 
+    .nu-mermaid-btn:disabled {
+        cursor: wait;
+        opacity: 0.6;
+    }
+
     :root:not([data-theme="light"]) .nu-mermaid-btn:hover {
         background: var(--nu-hover-bg);
     }