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

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-08-20
+
+### Fixed
+
+- **Starlight plugins that extend the Markdown processor no longer stop working.** Astro 7 renders Markdown with the Sätteri processor and hands every integration the same live processor object. Plugins extend the pipeline by changing that object. The theme replaced it with a `unified()` processor from two `astro:config:setup` hooks, which run after Starlight has already set up its plugins, so everything those plugins had registered was thrown away.
+
+  The visible effect was `starlight-links-validator` 0.25 or newer: it validated zero links on every build and still printed "All internal links are valid", so broken internal links passed unnoticed. Any plugin that configures itself against the Sätteri processor was affected the same way.
+
+  `defineNorthwesternConfig()` now sets `markdown.processor` to `unified()` while `astro.config.*` is evaluated, before `starlight()` is created. No plugin ever sees Sätteri, and the theme only extends the processor it is given instead of replacing it. A processor you configure yourself is left alone.
+
+- Mermaid no longer swaps the Markdown processor either. `astro-mermaid` 2.1 supports Sätteri on its own.
+
+## [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
@@ -185,7 +203,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.1...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.1...HEAD
+[1.6.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.0...v1.6.1
+[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

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

@@ -15,6 +15,7 @@ import {
 } from "./legacy-html-redirects";
 import { type NorthwesternMermaidOptions, northwesternMermaid } from "./mermaid";
 import { northwesternConfigOptionsSchema, validateSchema } from "./src/config-schema";
+import { type MarkdownConfigLike, withUnifiedProcessor } from "./src/markdown-processor";
 
 /**
  * Vite plugin that enables `pluginLineNumbers` for both markdown code blocks
@@ -144,11 +145,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;
@@ -255,9 +256,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");
@@ -299,17 +299,17 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     };
     const mergedPlugins = mergeStarlightPlugins(northwesternTheme(themeConfig), starlightPlugins, helperPlugins);
 
-    // Build integration array: before → [mermaid] → starlight → after → [legacy-html-redirects]
+    // 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()] : []),
     ];
@@ -334,6 +334,14 @@ export function defineNorthwesternConfig(options: NorthwesternConfigOptions): As
     return {
         ...astroConfig,
         integrations,
+        // Pin the Markdown processor to `unified()` here, at `astro.config.*`
+        // evaluation time, so `starlight()` and every Starlight plugin observes it
+        // from the start. Doing this later from an `astro:config:setup` hook means
+        // replacing a processor plugins have already registered against — which
+        // silently drops those registrations (see `src/markdown-processor.ts`).
+        markdown: withUnifiedProcessor(
+            astroConfig.markdown as MarkdownConfigLike | undefined,
+        ) as AstroUserConfig["markdown"],
         ...(mergedRedirects ? { redirects: mergedRedirects } : {}),
         vite: {
             ...existingViteConfig,

package/dist/config.d.ts

@@ -33,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;

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,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"}
+{"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;AA4EjF;;;;;;;;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,CAyI5F"}

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":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKhE;;;;;;;;;;;;;;;;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,CAyP/F"}

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` extend the active Markdown processor after Starlight and its
+ * plugins have configured it.
  *
  * @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":"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,gBAAgB,CAsD9F"}

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,11 +30,6 @@ 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>;
 /**
@@ -69,20 +48,8 @@ export declare const legacyHtmlRedirectsOptionsSchema: 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";
@@ -91,66 +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>>;
-    /**
-     * Generate `.html` redirects for every content page and rewrite the
-     * emitted redirect pages so the URL hash is preserved on forward.
-     *
-     * - `true`: scan `src/content/docs` with the defaults
-     * - `false` (default): do nothing
-     * - `object`: scan a custom content directory
-     */
     legacyHtmlRedirects: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         contentDir: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>>;
-    /**
-     * Escape hatch for advanced integration ordering.
-     *
-     * Use `before` for integrations that must run before Mermaid/Starlight,
-     * and `after` for integrations that should be appended after Starlight.
-     */
     integrations: z.ZodOptional<z.ZodObject<{
-        /**
-         * Integrations added before Mermaid and Starlight.
-         */
         before: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
-        /**
-         * Integrations added after Starlight.
-         */
         after: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     }, z.core.$strict>>;
 }, z.core.$loose>;

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,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"}
+{"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/markdown-processor.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Helpers for Astro's `markdown.processor` API.
+ *
+ * Astro 6.4 introduced `markdown.processor`, and Astro 7 changed its default
+ * from `unified()` (`@astrojs/markdown-remark`) to `satteri()`
+ * (`@astrojs/markdown-satteri`). Both are *live objects*: integrations and
+ * Starlight plugins extend the Markdown pipeline by mutating the processor
+ * instance they are handed — pushing into `processor.options.*Plugins`, or
+ * wrapping `processor.createRenderer`.
+ *
+ * That makes processor **replacement** destructive. Anything registered on the
+ * outgoing object is dropped, and because most registrations are optional
+ * behaviour, the failure is silent: `starlight-links-validator` swapped for a
+ * fresh processor simply validates zero links and reports success.
+ *
+ * The theme therefore installs a `unified()` processor in
+ * `defineNorthwesternConfig()` — at `astro.config.*` evaluation time, before
+ * `starlight()` is constructed and before any plugin can observe the default —
+ * and from then on only ever *extends* the processor it is given.
+ */
+/**
+ * Structural shape of `markdown.processor`.
+ *
+ * Declared locally because `AstroUserConfig["markdown"]` only gained the
+ * `processor` key in Astro 6.4, and the theme supports Astro 5 and 6 as well.
+ */
+export interface MarkdownProcessorLike {
+    name: string;
+    options?: {
+        remarkPlugins?: unknown[];
+        rehypePlugins?: unknown[];
+        mdastPlugins?: unknown[];
+        hastPlugins?: unknown[];
+        [key: string]: unknown;
+    };
+    createRenderer?: unknown;
+}
+/**
+ * Structural shape of `markdown` in an Astro config, including the keys the
+ * installed Astro version may not know about yet.
+ */
+export interface MarkdownConfigLike {
+    processor?: MarkdownProcessorLike;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    remarkRehype?: Record<string, unknown>;
+    gfm?: boolean;
+    smartypants?: unknown;
+    [key: string]: unknown;
+}
+/** A `unified()` processor from `@astrojs/markdown-remark`. */
+export declare function isUnifiedProcessor(processor: MarkdownProcessorLike | undefined): processor is MarkdownProcessorLike & {
+    options: {
+        rehypePlugins: unknown[];
+    };
+};
+/**
+ * Return a `markdown` config that is guaranteed to use a `unified()` processor.
+ *
+ * Call this while building the Astro config — before `starlight()` runs — so no
+ * plugin ever observes the Sätteri default. A processor the consumer supplied
+ * themselves is respected as-is (a non-`unified` one earns a warning, because
+ * several Starlight plugins the theme ships with only support `unified`).
+ *
+ * User-supplied `remarkPlugins` / `rehypePlugins` are deliberately *not* copied
+ * into the processor: Astro migrates those deprecated top-level arrays onto a
+ * `unified` processor itself (exactly once, tracked internally), and on Astro
+ * versions without `markdown.processor` they are the whole pipeline. Baking
+ * copies in here would run them twice.
+ */
+export declare function withUnifiedProcessor(markdown: MarkdownConfigLike | undefined, warn?: (message: string) => void): MarkdownConfigLike;
+/**
+ * Register a rehype plugin on the active Markdown pipeline.
+ *
+ * Returns a `markdown` config patch to hand to `updateConfig()`, or `undefined`
+ * when the plugin was added to the live processor and no config update is
+ * needed. Mutating `processor.options` is how Astro itself extends a processor
+ * after config resolution — the object identity survives config validation
+ * precisely so that late registrations still apply.
+ *
+ * A non-`unified` processor is left alone. Replacing it here is what used to
+ * discard Sätteri-registered plugins from unrelated Starlight plugins, so the
+ * theme warns instead of swapping behind their back.
+ */
+export declare function addRehypePlugin(markdown: MarkdownConfigLike | undefined, plugin: unknown, warn?: (message: string) => void): MarkdownConfigLike | undefined;
+//# sourceMappingURL=markdown-processor.d.ts.map

package/dist/src/markdown-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-processor.d.ts","sourceRoot":"","sources":["../../src/markdown-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACN,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;QAC1B,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;QACzB,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;QACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;IACF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,qBAAqB,GAAG,SAAS,GAC7C,SAAS,IAAI,qBAAqB,GAAG;IAAE,OAAO,EAAE;QAAE,aAAa,EAAE,OAAO,EAAE,CAAA;KAAE,CAAA;CAAE,CAEhF;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAmB,GAC/C,kBAAkB,CAwBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAmB,GAC/C,kBAAkB,GAAG,SAAS,CA6BhC"}

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

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { StarlightPlugin } from "@astrojs/starlight/types";
 import { nonEmptyStringSchema, northwesternThemeConfigSchema, validateSchema } from "./src/config-schema";
+import { addRehypePlugin, type MarkdownConfigLike } from "./src/markdown-processor";
 import rehypeTableScroll from "./src/rehype-table-scroll";
 
 /**
@@ -202,11 +203,18 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                 addIntegration({
                     name: "northwestern-theme-config",
                     hooks: {
-                        "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
+                        "astro:config:setup": ({ config: astroConfig, updateConfig: updateAstroConfig }) => {
+                            // Extend whichever Markdown pipeline is active — never replace it.
+                            // `defineNorthwesternConfig()` has already pinned a `unified()`
+                            // processor before any plugin could register against it.
+                            const markdownConfig = addRehypePlugin(
+                                astroConfig.markdown as MarkdownConfigLike | undefined,
+                                rehypeTableScroll,
+                                (message) => logger.warn(message),
+                            );
+
                             updateAstroConfig({
-                                markdown: {
-                                    rehypePlugins: [rehypeTableScroll],
-                                },
+                                ...(markdownConfig ? { markdown: markdownConfig } : {}),
                                 vite: {
                                     plugins: [
                                         {

package/mermaid.ts

@@ -421,10 +421,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` extend the active Markdown processor after Starlight and its
+ * plugins have configured it.
  *
  * @param options - Merged with Northwestern defaults. Set `toolbar: false` to
  *   disable the hover toolbar.
@@ -437,11 +436,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 +477,7 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
         hooks: {
             async "astro:config:setup"(params) {
                 const { default: mermaid } = await mermaidModulePromise;
+
                 const mermaidIntegration = mermaid({
                     ...lightConfig,
                     ...overrides,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -68,11 +68,12 @@
     "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",
@@ -89,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/markdown-processor.ts

@@ -0,0 +1,168 @@
+/**
+ * Helpers for Astro's `markdown.processor` API.
+ *
+ * Astro 6.4 introduced `markdown.processor`, and Astro 7 changed its default
+ * from `unified()` (`@astrojs/markdown-remark`) to `satteri()`
+ * (`@astrojs/markdown-satteri`). Both are *live objects*: integrations and
+ * Starlight plugins extend the Markdown pipeline by mutating the processor
+ * instance they are handed — pushing into `processor.options.*Plugins`, or
+ * wrapping `processor.createRenderer`.
+ *
+ * That makes processor **replacement** destructive. Anything registered on the
+ * outgoing object is dropped, and because most registrations are optional
+ * behaviour, the failure is silent: `starlight-links-validator` swapped for a
+ * fresh processor simply validates zero links and reports success.
+ *
+ * The theme therefore installs a `unified()` processor in
+ * `defineNorthwesternConfig()` — at `astro.config.*` evaluation time, before
+ * `starlight()` is constructed and before any plugin can observe the default —
+ * and from then on only ever *extends* the processor it is given.
+ */
+
+import { unified } from "@astrojs/markdown-remark";
+
+/**
+ * Structural shape of `markdown.processor`.
+ *
+ * Declared locally because `AstroUserConfig["markdown"]` only gained the
+ * `processor` key in Astro 6.4, and the theme supports Astro 5 and 6 as well.
+ */
+export interface MarkdownProcessorLike {
+    name: string;
+    options?: {
+        remarkPlugins?: unknown[];
+        rehypePlugins?: unknown[];
+        mdastPlugins?: unknown[];
+        hastPlugins?: unknown[];
+        [key: string]: unknown;
+    };
+    createRenderer?: unknown;
+}
+
+/**
+ * Structural shape of `markdown` in an Astro config, including the keys the
+ * installed Astro version may not know about yet.
+ */
+export interface MarkdownConfigLike {
+    processor?: MarkdownProcessorLike;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    remarkRehype?: Record<string, unknown>;
+    gfm?: boolean;
+    smartypants?: unknown;
+    [key: string]: unknown;
+}
+
+/** A `unified()` processor from `@astrojs/markdown-remark`. */
+export function isUnifiedProcessor(
+    processor: MarkdownProcessorLike | undefined,
+): processor is MarkdownProcessorLike & { options: { rehypePlugins: unknown[] } } {
+    return processor?.name === "unified" && Array.isArray(processor.options?.rehypePlugins);
+}
+
+/**
+ * Plugins registered against a non-`unified` processor (Sätteri's `mdastPlugins`
+ * / `hastPlugins`).
+ *
+ * These use a different plugin system than remark/rehype — a visitor object from
+ * `defineHastPlugin()`, not a unified transformer — so they cannot be carried
+ * across when a processor is replaced. Counting them is how the theme detects
+ * that a replacement would silently drop somebody else's work.
+ */
+function countProcessorPlugins(processor: MarkdownProcessorLike): number {
+    const { mdastPlugins, hastPlugins } = processor.options ?? {};
+    return (
+        (Array.isArray(mdastPlugins) ? mdastPlugins.length : 0) + (Array.isArray(hastPlugins) ? hastPlugins.length : 0)
+    );
+}
+
+/**
+ * Return a `markdown` config that is guaranteed to use a `unified()` processor.
+ *
+ * Call this while building the Astro config — before `starlight()` runs — so no
+ * plugin ever observes the Sätteri default. A processor the consumer supplied
+ * themselves is respected as-is (a non-`unified` one earns a warning, because
+ * several Starlight plugins the theme ships with only support `unified`).
+ *
+ * User-supplied `remarkPlugins` / `rehypePlugins` are deliberately *not* copied
+ * into the processor: Astro migrates those deprecated top-level arrays onto a
+ * `unified` processor itself (exactly once, tracked internally), and on Astro
+ * versions without `markdown.processor` they are the whole pipeline. Baking
+ * copies in here would run them twice.
+ */
+export function withUnifiedProcessor(
+    markdown: MarkdownConfigLike | undefined,
+    warn: (message: string) => void = console.warn,
+): MarkdownConfigLike {
+    const config = markdown ?? {};
+
+    if (config.processor) {
+        if (!isUnifiedProcessor(config.processor)) {
+            warn(
+                `[northwestern-starlight-theme] \`markdown.processor\` is set to \`${config.processor.name}()\`. ` +
+                    "The theme's scrollable tables and Starlight plugins such as `starlight-image-zoom` require the " +
+                    "`unified()` processor from `@astrojs/markdown-remark`. Remove `markdown.processor` to let the " +
+                    "theme configure it, or set it to `unified({ ... })`.",
+            );
+        }
+
+        return config;
+    }
+
+    return {
+        ...config,
+        processor: unified({
+            remarkRehype: config.remarkRehype,
+            gfm: config.gfm,
+            smartypants: config.smartypants,
+        } as Parameters<typeof unified>[0]) as MarkdownProcessorLike,
+    };
+}
+
+/**
+ * Register a rehype plugin on the active Markdown pipeline.
+ *
+ * Returns a `markdown` config patch to hand to `updateConfig()`, or `undefined`
+ * when the plugin was added to the live processor and no config update is
+ * needed. Mutating `processor.options` is how Astro itself extends a processor
+ * after config resolution — the object identity survives config validation
+ * precisely so that late registrations still apply.
+ *
+ * A non-`unified` processor is left alone. Replacing it here is what used to
+ * discard Sätteri-registered plugins from unrelated Starlight plugins, so the
+ * theme warns instead of swapping behind their back.
+ */
+export function addRehypePlugin(
+    markdown: MarkdownConfigLike | undefined,
+    plugin: unknown,
+    warn: (message: string) => void = console.warn,
+): MarkdownConfigLike | undefined {
+    const config = markdown ?? {};
+    const processor = config.processor;
+
+    // Astro < 6.4: the top-level plugin arrays are the entire pipeline.
+    if (!processor) {
+        return { rehypePlugins: [...(config.rehypePlugins ?? []), plugin] };
+    }
+
+    if (isUnifiedProcessor(processor)) {
+        if (!processor.options.rehypePlugins.includes(plugin)) {
+            processor.options.rehypePlugins.push(plugin);
+        }
+
+        return undefined;
+    }
+
+    const registered = countProcessorPlugins(processor);
+    warn(
+        `[northwestern-starlight-theme] Markdown is rendered by the \`${processor.name}()\` processor, which the theme ` +
+            "does not extend. Scrollable table wrappers are disabled for this build" +
+            (registered > 0
+                ? `, and converting the processor would drop ${registered} plugin(s) other integrations registered on it. `
+                : ". ") +
+            "Use `defineNorthwesternConfig()` (it installs a `unified()` processor for you) or set " +
+            "`markdown.processor: unified({ ... })` from `@astrojs/markdown-remark`.",
+    );
+
+    return undefined;
+}

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);
     }