refactor(starlight): use Starlight <Aside> for Mintlify admonitions

The React shims in mintlify-compat.jsx rebuilt the Starlight aside
markup by hand and silently dropped the <svg> inside the icon span, so
every Warning/Note/Info/Tip rendered with an empty icon slot. Replace
the hand-rolled components with an AST rewrite (same pattern as
rewriteCodeGroup): rewriteAsides maps <Warning>/<Note>/<Info>/<Tip>
to <Aside type="caution|note|note|tip"> before injectMdxImports runs.
The shim now re-exports Aside directly from @astrojs/starlight/components,
and GLOBAL_MDX_NAMES drops the rewritten names in favor of Aside. Icons,
ARIA semantics, and future Starlight aside updates come along for free.

Author: adrum

starlight/astro.config.mjs

@@ -6,6 +6,7 @@ import react from "@astrojs/react";
 import mdx from "@astrojs/mdx";
 import { injectMdxImports } from "./src/remark/inject-mdx-imports.mjs";
 import { rewriteCodeGroup } from "./src/remark/rewrite-code-group.mjs";
+import { rewriteAsides } from "./src/remark/rewrite-asides.mjs";
 import { sidebarV1 } from "./src/sidebars/v1.mjs";
 import { sidebarV2 } from "./src/sidebars/v2.mjs";
 import { sidebarV3 } from "./src/sidebars/v3.mjs";
@@ -18,14 +19,13 @@ const mintlifyShim = path.resolve(here, "src/components/mintlify-compat.jsx");
 // Names the shim re-exports (both its own components and re-exported
 // Starlight primitives). Every .mdx file gets these injected globally,
 // except when the file already imports a binding with the same name.
-// CodeGroup is intentionally NOT here — it's rewritten at the AST level
-// by the rewriteCodeGroup remark plugin, so no runtime component is needed.
+//
+// Intentionally NOT in this list:
+//   - CodeGroup → rewritten to a div tree by rewriteCodeGroup
+//   - Warning/Note/Info/Tip → rewritten to <Aside type="..."> by rewriteAsides
 const GLOBAL_MDX_NAMES = [
   "Card",
-  "Warning",
-  "Note",
-  "Info",
-  "Tip",
+  "Aside",
   "Columns",
   "Steps",
   "Step",
@@ -72,10 +72,11 @@ export default defineConfig({
   },
   markdown: {
     remarkPlugins: [
-      // Must run BEFORE injectMdxImports: CodeGroup rewriting removes the
-      // <CodeGroup> element entirely, so we don't need to inject an import
-      // for a component that's already gone.
+      // Element rewrites must run BEFORE injectMdxImports — they replace
+      // the original tag names so the import injector knows it doesn't
+      // need to provide bindings for the originals.
       rewriteCodeGroup,
+      rewriteAsides,
       [
         injectMdxImports,
         {

starlight/src/components/mintlify-compat.jsx

@@ -1,29 +1,15 @@
 import React from "react";
 
-// Re-export Starlight's Card so content files outside the project root
-// (symlinked v1/v2/v3 trees) can reach it via this shim's absolute path.
-// Auto-import maps <Card> → this re-export.
-export { Card } from "@astrojs/starlight/components";
-
-// --- Admonition wrappers -> Starlight aside CSS classes ---
-
-const Aside = ({ type, children }) => (
-  <aside
-    aria-label={type}
-    className={`starlight-aside starlight-aside--${type}`}
-  >
-    <p className="starlight-aside__title">
-      <span className="starlight-aside__icon" aria-hidden="true" />
-      {type[0].toUpperCase() + type.slice(1)}
-    </p>
-    <section className="starlight-aside__content">{children}</section>
-  </aside>
-);
-
-export const Warning = ({ children }) => <Aside type="caution">{children}</Aside>;
-export const Note = ({ children }) => <Aside type="note">{children}</Aside>;
-export const Info = ({ children }) => <Aside type="note">{children}</Aside>;
-export const Tip = ({ children }) => <Aside type="tip">{children}</Aside>;
+// Re-export Starlight components from this shim so content files outside
+// the project root (symlinked v1/v2/v3 trees) can reach them via the
+// shim's absolute path — Vite can't resolve `@astrojs/starlight/...`
+// from /docs/v* MDX files because they live outside the project's
+// `node_modules` lookup chain.
+//
+// `Aside` is referenced via the rewriteAsides remark plugin which maps
+// <Warning>/<Note>/<Info>/<Tip> → <Aside type="...">. `Card` is
+// referenced directly by content files.
+export { Aside, Card } from "@astrojs/starlight/components";
 
 // --- Framework filter wrappers ---
 // Emit a wrapper <div> with `data-framework-only` listing every framework

starlight/src/remark/rewrite-asides.mjs

@@ -0,0 +1,38 @@
+import { visit } from "unist-util-visit";
+
+/**
+ * Remark plugin that rewrites Mintlify-style admonition tags into
+ * Starlight's native <Aside> component. The original wrappers were
+ * React shims that re-built the aside markup by hand and silently
+ * dropped Starlight's icon SVGs — using <Aside> directly gets the
+ * icons, ARIA semantics, and any future styling for free.
+ *
+ * Mappings:
+ *   <Warning>  →  <Aside type="caution">
+ *   <Note>     →  <Aside type="note">
+ *   <Info>     →  <Aside type="note">    // Mintlify "info" ≈ Starlight "note"
+ *   <Tip>      →  <Aside type="tip">
+ *
+ * Children pass through unchanged. The rewrite runs before
+ * injectMdxImports so the resulting <Aside> tag picks up its global
+ * import from the shim re-export.
+ */
+const ASIDE_TYPES = {
+  Warning: "caution",
+  Note: "note",
+  Info: "note",
+  Tip: "tip",
+};
+
+export function rewriteAsides() {
+  return function transformer(tree) {
+    visit(tree, "mdxJsxFlowElement", (node) => {
+      const type = ASIDE_TYPES[node.name];
+      if (!type) return;
+      node.name = "Aside";
+      node.attributes = [
+        { type: "mdxJsxAttribute", name: "type", value: type },
+      ];
+    });
+  };
+}