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

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
@@ -191,7 +203,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI plugin compatibility with method badge preservation
 - Reduced motion support for transitions
 
-[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.0...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

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
@@ -333,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.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,CAiI5F"}
+{"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":"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"}
+{"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

@@ -69,8 +69,8 @@ export declare const darkMermaidConfig: AstroMermaidOptions;
  * This function is only needed for manual setups.
  *
  * **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.
+ * `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.

package/dist/mermaid.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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/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/index.ts

@@ -3,9 +3,9 @@ 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 { addRehypePlugin, type MarkdownConfigLike } from "./src/markdown-processor";
 import rehypeTableScroll from "./src/rehype-table-scroll";
 
 /**
@@ -204,24 +204,17 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                     name: "northwestern-theme-config",
                     hooks: {
                         "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],
-                                      };
+                            // 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: markdownConfig,
+                                ...(markdownConfig ? { markdown: markdownConfig } : {}),
                                 vite: {
                                     plugins: [
                                         {

package/mermaid.ts

@@ -1,4 +1,3 @@
-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";
@@ -423,8 +422,8 @@ export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidC
  * This function is only needed for manual setups.
  *
  * **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.
+ * `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.
@@ -478,31 +477,6 @@ 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,
@@ -511,7 +485,7 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
                     mermaidConfig: mergedLightMermaidConfig,
                 });
 
-                await mermaidIntegration.hooks["astro:config:setup"]?.(mermaidHookParams);
+                await mermaidIntegration.hooks["astro:config:setup"]?.(params);
 
                 params.injectScript(
                     "page",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",

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