@writedocs/generator 0.4.9 → 0.4.11

package/src/components/GitHubRepo.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <GitHub.Repo repo="owner/name" variant="inset|flat"> - a card
 // linking to a public GitHub repository. Attached as GitHub.Repo in
 // components/compound.ts. `repo` is an "owner/name" slug or a full
@@ -27,7 +28,7 @@ const valid = /^[\w.-]+\/[\w.-]+$/.test(slug);
 ---
 {valid && (
   <a
-    class:list={['wd-github-repo', `wd-github-repo-${variant}`]}
+    class:list={['wd-github-repo', `wd-github-repo-${variant}`, extraClasses(Astro.props)]}
     href={`https://github.com/${slug}`}
     target="_blank"
     rel="noopener noreferrer"

package/src/components/Hint.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Inline, text-level component - unlike every other built-in here
 // (Callout, Card, Accordion, ...), which are all block-level and get
 // their own line, a Hint sits mid-sentence: `word <Hint tip="...">this
@@ -28,7 +29,7 @@ const { tip, headline, cta, href } = Astro.props as Props;
 const hasLink = Boolean(cta && href);
 ---
 
-<span class:list={["wd-hint", { "wd-hint-rich": Boolean(headline) || hasLink }]} tabindex="0">
+<span class:list={["wd-hint", { "wd-hint-rich": Boolean(headline) || hasLink }, extraClasses(Astro.props)]} tabindex="0">
   <span class="wd-hint-trigger"><slot /></span>
   <span class="wd-hint-tooltip" role="tooltip">
     {headline && <span class="wd-hint-headline">{headline}</span>}

package/src/components/Icon.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Renders either a real icon (via `icon`) or a custom image (via
 // `src`) inline with surrounding text - modeled on Mintlify's own Icon
 // (https://www.mintlify.com/docs/components/icons), which documents
@@ -42,9 +43,9 @@ const iconStyle =
 
 {
   src ? (
-    <img src={src} alt={alt} class="wd-icon-image" style={`height:${height}`} />
+    <img src={src} alt={alt} class:list={["wd-icon-image", extraClasses(Astro.props)]} style={`height:${height}`} />
   ) : icon ? (
-    <AppIcon icon={icon} class="wd-icon-inline" style={iconStyle} />
+    <AppIcon icon={icon} class={["wd-icon-inline", ...extraClasses(Astro.props)].join(" ")} style={iconStyle} />
   ) : null
 }
 <style>

package/src/components/Image.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Block-level (own line, centered) - unlike Hint (inline/text-level),
 // this is meant to be dropped in on its own the way Callout/Card are.
 //
@@ -65,7 +66,7 @@ const sizeStyle = size ? `--wd-image-size:${size}` : undefined;
 ---
 
 <figure
-  class:list={["wd-image-figure", caption && "wd-image-figure-framed", srcDark && "wd-image-has-dark"]}
+  class:list={["wd-image-figure", caption && "wd-image-figure-framed", srcDark && "wd-image-has-dark", extraClasses(Astro.props)]}
   style={sizeStyle}
 >
   <img src={src} alt={alt} class="wd-image wd-image-light" nozoom={noZoom || undefined} />

package/src/components/Info.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="info" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="info" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/Note.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="note" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="note" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/Panel.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Panel> - content pinned to the right-hand column on desktop,
 // in place of the table of contents. It's the same docking
 // RequestExample/ResponseExample already use (initExamplePanels() in
@@ -8,4 +9,4 @@
 // with no table-of-contents column (any mode but `default`), the Panel
 // stays where it is in the page.
 ---
-<div class="wd-example-panel wd-panel"><slot /></div>
+<div class:list={["wd-example-panel wd-panel", extraClasses(Astro.props)]}><slot /></div>

package/src/components/Parameter.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // The name+type+description row used throughout API reference content -
 // modeled directly on Mintlify's own ParamField/ResponseField
 // (https://www.mintlify.com/docs/components/expandables), which this
@@ -38,7 +39,7 @@ const { name, type, required = false, default: defaultValue, deprecated = false,
 const hasDefault = defaultValue !== undefined && defaultValue !== null && defaultValue !== "";
 ---
 
-<div class:list={["wd-parameter", { "wd-parameter-deprecated": deprecated }]}>
+<div class:list={["wd-parameter", { "wd-parameter-deprecated": deprecated }, extraClasses(Astro.props)]}>
   <div class="wd-parameter-head">
     {pre.map((label) => <span class="wd-parameter-label">{label}</span>)}
     <span class="wd-parameter-name">{name}</span>

package/src/components/Prompt.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Prompt> - a ready-made AI prompt: a card showing
 // `description` (inline Markdown) and an optional icon, with actions to
 // copy the prompt or open it in Cursor. The prompt itself is the slot; it's
@@ -27,7 +28,7 @@ const { description, icon, actions = ['copy'], _text } = Astro.props as Props;
 const cursorHref = _text ? `https://cursor.com/link/prompt?text=${encodeURIComponent(_text)}` : null;
 const showCursor = actions.includes('cursor') && cursorHref !== null && cursorHref.length <= 10000;
 ---
-<div class="wd-prompt">
+<div class:list={["wd-prompt", extraClasses(Astro.props)]}>
   <div class="wd-prompt-head">
     {icon && <AppIcon icon={icon} class="wd-prompt-icon" />}
     {description && <div class="wd-prompt-description" set:html={inlineMarkdown(description)} />}

package/src/components/RequestExample.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Pins its code example(s) in the right sidebar - in place of the page's
 // normal table of contents - on desktop; falls back to a plain in-place
 // CodeGroup on narrower viewports where that sidebar column doesn't
@@ -26,7 +27,7 @@ interface Props {
 }
 const { dropdown = false } = Astro.props as Props;
 ---
-<div class="wd-example-panel wd-request-example">
+<div class:list={["wd-example-panel wd-request-example", extraClasses(Astro.props)]}>
   <CodeGroup dropdown={dropdown}>
     <slot />
   </CodeGroup>

package/src/components/ResponseExample.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // See RequestExample.astro's own comment - identical in every respect
 // except the marker class (wd-response-example vs wd-request-example),
 // which src/scripts/example-panels.ts uses to always dock Response
@@ -12,7 +13,7 @@ interface Props {
 }
 const { dropdown = false } = Astro.props as Props;
 ---
-<div class="wd-example-panel wd-response-example">
+<div class:list={["wd-example-panel wd-response-example", extraClasses(Astro.props)]}>
   <CodeGroup dropdown={dropdown}>
     <slot />
   </CodeGroup>

package/src/components/Searchbar.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Wraps a GFM table (or any other block-level slot content, though a
 // table is the intended/primary use case) with a text input above it
 // that live-filters rows by their own text content - "let users filter
@@ -21,7 +22,7 @@ interface Props {
 const { placeholder = "Search..." } = Astro.props as Props;
 ---
 
-<div class="wd-searchbar">
+<div class:list={["wd-searchbar", extraClasses(Astro.props)]}>
   <input type="text" class="wd-searchbar-input" placeholder={placeholder} aria-label={placeholder} />
   <div class="wd-searchbar-content">
     <slot />

package/src/components/Step.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 import AppIcon from './AppIcon.astro';
 // `icon`, `stepNumber` and `titleSize` are Mintlify's. `icon` replaces the
 // number in the step's circle. `stepNumber` sets this step's number; the
@@ -15,7 +16,7 @@ const { title, icon, stepNumber, titleSize = 'p' } = Astro.props as Props;
 const style = typeof stepNumber === 'number' ? `counter-set: wd-step ${stepNumber - 1}` : undefined;
 const TitleTag = titleSize === 'h2' || titleSize === 'h3' ? titleSize : 'p';
 ---
-<div class:list={['wd-step', { 'wd-step-has-icon': Boolean(icon) }]} style={style}>
+<div class:list={['wd-step', { 'wd-step-has-icon': Boolean(icon) }, extraClasses(Astro.props)]} style={style}>
   {icon && <AppIcon icon={icon} class="wd-step-icon" />}
   {
     title &&

package/src/components/Steps.astro

@@ -1,4 +1,7 @@
-<div class="wd-steps"><slot /></div>
+---
+import { extraClasses } from './class-names';
+---
+<div class:list={["wd-steps", extraClasses(Astro.props)]}><slot /></div>
 <style is:global>
   .wd-steps {
     counter-reset: wd-step;

package/src/components/Tab.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 import AppIcon from './AppIcon.astro';
 // `icon` is Mintlify's: shown before the title in the tab's button. The
 // button is built client-side by Tabs.astro, which moves this hidden,
@@ -9,7 +10,7 @@ interface Props {
 }
 const { title, icon } = Astro.props as Props;
 ---
-<div class="wd-tab" data-title={title}>
+<div class:list={["wd-tab", extraClasses(Astro.props)]} data-title={title}>
   {icon && <span class="wd-tab-icon-src" hidden><AppIcon icon={icon} class="wd-tabs-btn-icon" /></span>}
   <slot />
 </div>

package/src/components/Tabs.astro

@@ -1,11 +1,12 @@
 ---
+import { extraClasses } from './class-names';
 // `defaultTabIndex` is Mintlify's: which tab (0-based) starts selected.
 interface Props {
   defaultTabIndex?: number;
 }
 const { defaultTabIndex = 0 } = Astro.props as Props;
 ---
-<div class="wd-tabs" data-default-index={defaultTabIndex}>
+<div class:list={["wd-tabs", extraClasses(Astro.props)]} data-default-index={defaultTabIndex}>
   <slot />
 </div>
 <script>

package/src/components/Tile.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Tile> - a visual preview (the slot, usually an image or a
 // light/dark image pair) on a patterned background, with a title and
 // description under it. Usually laid out in a <Columns> grid. `title`
@@ -13,7 +14,7 @@ interface Props {
 const { href, title, description } = Astro.props as Props;
 const Tag = href ? 'a' : 'div';
 ---
-<Tag class="wd-tile" href={href}>
+<Tag class:list={["wd-tile", extraClasses(Astro.props)]} href={href}>
   <div class="wd-tile-preview"><slot /></div>
   {title && <div class="wd-tile-title" set:html={inlineMarkdown(title)} />}
   {description && <div class="wd-tile-description">{description}</div>}

package/src/components/Tip.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="tip" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="tip" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/TreeFile.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Tree.File name="..."> - see Tree.astro. `highlight` marks it
 // as the active item.
 import AppIcon from './AppIcon.astro';
@@ -8,7 +9,7 @@ interface Props {
 }
 const { name, highlight = false } = Astro.props as Props;
 ---
-<li class:list={['wd-tree-item', 'wd-tree-file', { 'wd-tree-highlight': highlight }]} role="treeitem" tabindex="-1">
+<li class:list={['wd-tree-item', 'wd-tree-file', { 'wd-tree-highlight': highlight }, extraClasses(Astro.props)]} role="treeitem" tabindex="-1">
   <span class="wd-tree-row">
     <span class="wd-tree-chevron wd-tree-chevron-spacer" aria-hidden="true"></span>
     <AppIcon icon="lucide:file" class="wd-tree-icon" />

package/src/components/TreeFolder.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Tree.Folder name="..."> - see Tree.astro. `defaultOpen`
 // starts it expanded; `openable={false}` makes it a fixed, non-toggling
 // folder (shown open or closed per `defaultOpen`); `highlight` marks it as
@@ -13,7 +14,7 @@ interface Props {
 const { name, defaultOpen = false, openable = true, highlight = false } = Astro.props as Props;
 ---
 <li
-  class:list={['wd-tree-item', 'wd-tree-folder', { 'wd-tree-highlight': highlight, 'wd-tree-static': !openable }]}
+  class:list={['wd-tree-item', 'wd-tree-folder', { 'wd-tree-highlight': highlight, 'wd-tree-static': !openable }, extraClasses(Astro.props)]}
   role="treeitem"
   aria-expanded={defaultOpen ? 'true' : 'false'}
   tabindex="-1"

package/src/components/Update.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Update> - one changelog entry: `label` (usually a date or
 // version) in a left column that sticks while its content scrolls, with
 // `description` and `tags` under it. The label is a linkable anchor, deduped
@@ -25,7 +26,7 @@ function slugify(value: string): string {
 }
 const id = _titleId ?? slugify(label);
 ---
-<section class="wd-update" data-update-tags={JSON.stringify(tags)}>
+<section class:list={["wd-update", extraClasses(Astro.props)]} data-update-tags={JSON.stringify(tags)}>
   <div class="wd-update-meta">
     <div class="wd-update-label" id={id}>
       <a href={`#${id}`}>{label}</a>

package/src/components/Video.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Renders either a native <video> or an <iframe> embed from the same
 // `src` prop, auto-detected rather than requiring the author to pick -
 // `src="media/clip.mp4"` (a direct video file, local or remote) gets a
@@ -57,7 +58,7 @@ const sizeStyle = width ? `--wd-video-size:${width}` : undefined;
 const effectiveMuted = muted || autoplay;
 ---
 
-<figure class:list={["wd-video-figure", caption && "wd-video-figure-framed"]} style={sizeStyle}>
+<figure class:list={["wd-video-figure", caption && "wd-video-figure-framed", extraClasses(Astro.props)]} style={sizeStyle}>
   {
     isFile ? (
       <video

package/src/components/View.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <View title="..." icon="..."> - content for one of several
 // alternatives (a language, a framework) on the same page. Every distinct
 // `title` on the page becomes an option in one switcher, placed under the
@@ -16,7 +17,7 @@ interface Props {
 }
 const { title, icon } = Astro.props as Props;
 ---
-<div class="wd-view" data-view-title={title}>
+<div class:list={["wd-view", extraClasses(Astro.props)]} data-view-title={title}>
   {icon && <span class="wd-view-icon-src" hidden><AppIcon icon={icon} class="wd-view-icon" /></span>}
   <slot />
 </div>

package/src/components/Warning.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="warning" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="warning" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/class-names.ts

@@ -0,0 +1,8 @@
+// Every built-in component takes extra classes for its root element - as
+// `className` (how MDX, and Mintlify content, passes it) or `class` (Astro's
+// own spelling). Components add extraClasses(Astro.props) to their root
+// element's class:list; with neither set it adds nothing, so the rendered
+// markup is unchanged.
+export function extraClasses(props: Record<string, unknown>): string[] {
+  return [props.class, props.className].filter((c): c is string => typeof c === 'string' && c.trim() !== '');
+}

package/src/components/index.ts

@@ -50,6 +50,8 @@ export { default as Check } from './Check.astro';
 export { default as ParamField } from './ParamField.astro';
 export { default as ResponseField } from './ResponseField.astro';
 export { default as Columns } from './Columns.astro';
+export { default as Column } from './Column.astro';
+export { default as CodeBlock } from './CodeBlock.astro';
 export { default as Tooltip } from './Tooltip.astro';
 export { default as Update } from './Update.astro';
 export { default as Tile } from './Tile.astro';

package/src/content.config.ts

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { pageFrontmatterSchema, findAllPages } from './lib/config';
+import { titleFromPath } from './lib/pages.js';
 import { writedocsTempDir } from './lib/writedocs-temp-dir.js';
 
 const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
@@ -51,11 +52,31 @@ function skipIfMissing(inner: Loader): Loader {
     name: inner.name,
     load: async (context) => {
       if (!fs.existsSync(generatedDocsBase)) return;
-      return inner.load(context);
+      return inner.load(withTitleFallback(context));
     },
   };
 }
 
+// A page with no `title` in its frontmatter gets one from its file name,
+// before the schema (which requires `title`) sees it - Mintlify's rule, so
+// a migrated page that relied on it builds with the same title. See
+// titleFromPath() in lib/pages.js; `writedocs validate` applies the same
+// default (lib/content-check.js).
+type LoaderContext = Parameters<Loader['load']>[0];
+function withTitleFallback(context: LoaderContext): LoaderContext {
+  return {
+    ...context,
+    parseData: (props) =>
+      context.parseData({
+        ...props,
+        data:
+          typeof props.data?.title === 'string'
+            ? props.data
+            : { ...props.data, title: titleFromPath(props.filePath ?? props.id) },
+      }),
+  };
+}
+
 const generatedDocs = defineCollection({
   loader: skipIfMissing(glob({ pattern: '**/*.{md,mdx}', base: generatedDocsBase })),
   schema: docsSchema,
@@ -135,7 +156,7 @@ function livePages(dir: string, base: URL): Loader {
           for (const id of store.keys()) store.delete(id);
           return;
         }
-        await glob({ pattern: files, base }).load({ ...context, watcher: undefined });
+        await glob({ pattern: files, base }).load({ ...withTitleFallback(context), watcher: undefined });
       }
 
       await resync();

package/src/lib/content-check.js

@@ -8,19 +8,23 @@
 //     pageFrontmatterSchema the build uses) or isn't valid YAML
 //   - an .mdx file doesn't parse as MDX
 //   - writedocs.json's navigation lists a page that doesn't exist
+//   - a redirect is a pattern (`/old/:slug`) rather than one exact path
 // Warnings - the build succeeds, but not as written:
 //   - an unknown component (the build shows only its content - see
 //     lib/mdx-unknown-components.js)
 //   - an icon name no installed icon set has (the build leaves it out -
 //     see AppIcon.astro), in a component's `icon`, a page's `icon`, or
 //     writedocs.json
+//   - a built-in component inside a page component that runs as React,
+//     where it renders simplified (lib/mdx-inline-react.js)
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
-import { findAllPages, fileIdForPath } from './pages.js';
+import { findAllPages, fileIdForPath, titleFromPath } from './pages.js';
 import { iconExists } from './icons.js';
 import { findUnknownComponents } from './mdx-unknown-components.js';
+import { findInteractiveComponents, simplifiedBuiltinMessage } from './mdx-inline-react.js';
 import { pageFrontmatterSchema, createJsonLocator } from './config-schema.js';
 
 /** An issue: { file, line?, message, suggestion? } - `file` relative to the
@@ -75,8 +79,10 @@ async function checkPage(contentDir, rel, errors, warnings) {
   // returns from its cache (findAllPages() already parsed every page once).
   const frontmatterText = raw.match(/^---[^\n]*\n([\s\S]*?)\n---/)?.[1] ?? '';
 
-  // Frontmatter against the same schema the build uses.
-  const result = pageFrontmatterSchema.safeParse(parsed.data);
+  // Frontmatter against the same schema the build uses - with the same
+  // file-name default for a missing title (content.config.ts).
+  const data = typeof parsed.data?.title === 'string' ? parsed.data : { ...parsed.data, title: titleFromPath(rel) };
+  const result = pageFrontmatterSchema.safeParse(data);
   if (!result.success) {
     for (const i of result.error.issues) {
       const key = String(i.path[0] ?? '');
@@ -122,6 +128,14 @@ async function checkPage(contentDir, rel, errors, warnings) {
       )
     );
   }
+  // Built-ins inside a page component that runs as React - they render
+  // simplified there (lib/mdx-inline-react.js, which the build warns from
+  // with the same words).
+  for (const use of findInteractiveComponents(tree, parsed.content).simplified) {
+    const line = parsed.content.slice(0, use.offset).split('\n').length + lineOffset;
+    const { message, suggestion } = simplifiedBuiltinMessage(use);
+    warnings.push(issue(rel, line, message, suggestion));
+  }
   visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
     const attr = node.attributes?.find((a) => a.type === 'mdxJsxAttribute' && a.name === 'icon');
     if (!attr || typeof attr.value !== 'string' || iconExists(attr.value)) return;
@@ -195,18 +209,34 @@ export async function checkContent(contentDir, configText) {
     const ids = new Set(pages.map(fileIdForPath));
     for (const ref of navigationReferences(config.navigation)) {
       if (ids.has(ref.id)) continue;
-      const withoutFrontmatter = ['.mdx', '.md'].some((ext) => fs.existsSync(path.join(contentDir, `${ref.id}${ext}`)));
+      const folderIndex = ref.id.endsWith('/index') && ids.has(ref.id.replace(/\/index$/, ''));
       errors.push(
         issue(
           'writedocs.json',
           locate(ref.path)?.line,
           `The navigation lists page "${ref.id}", but there's no page with that path.`,
-          withoutFrontmatter
-            ? `${ref.id} exists but has no frontmatter, so it isn't a page - add a frontmatter block with at least a title.`
+          folderIndex
+            ? `A folder's index page is listed by the folder's path - write "${ref.id.replace(/\/index$/, '')}".`
             : `Create ${ref.id}.mdx, or fix the path (it's relative to the folder writedocs.json is in, without the extension).`
         )
       );
     }
+    // A redirect is one exact path - a Mintlify-style pattern (`/old/:slug`,
+    // `/old/*`) becomes a literal page path, and the build fails on it.
+    (Array.isArray(config.redirects) ? config.redirects : []).forEach((r, i) => {
+      for (const key of ['source', 'destination']) {
+        const value = r?.[key];
+        if (typeof value !== 'string' || !/(^|\/):[A-Za-z_]|\*/.test(value)) continue;
+        errors.push(
+          issue(
+            'writedocs.json',
+            locate(['redirects', i, key])?.line,
+            `Redirect ${key} "${value}" is a pattern - writedocs redirects match one exact path.`,
+            'Replace it with one redirect per exact path.'
+          )
+        );
+      }
+    });
     for (const { icon, path: jsonPath } of configIcons(config)) {
       if (iconExists(icon)) continue;
       const { message, suggestion } = unknownIconMessage(icon);

package/src/lib/mdx-auto-hydrate.js

@@ -63,6 +63,18 @@ export function remarkAutoHydrateSnippets() {
         (attr) => attr.type === 'mdxJsxAttribute' && typeof attr.name === 'string' && attr.name.startsWith(CLIENT_ATTR_PREFIX)
       );
       if (hasClientDirective) return;
+      // A component handed over as a prop (`Renderer={MyBlock}`, a pattern
+      // Mintlify content uses) can't be hydrated: Astro sends an island's
+      // props to the browser as data, and a function doesn't survive that -
+      // it arrives as null and React throws. Such a usage is rendered on the
+      // server only; everything else about it still works.
+      const passesComponent = attributes.some(
+        (attr) =>
+          attr.type === 'mdxJsxAttribute' &&
+          attr.value?.type === 'mdxJsxAttributeValueExpression' &&
+          /^\s*[A-Z][A-Za-z0-9]*\s*$/.test(attr.value.value ?? '')
+      );
+      if (passesComponent) return;
       attributes.push({ type: 'mdxJsxAttribute', name: 'client:load', value: null });
       node.attributes = attributes;
     });

package/src/lib/mdx-inject-builtins.js

@@ -38,6 +38,8 @@ export const BUILTIN_COMPONENT_NAMES = [
   'ParamField',
   'ResponseField',
   'Columns',
+  'Column',
+  'CodeBlock',
   'Tooltip',
   'Update',
   'Tile',
@@ -95,6 +97,19 @@ export function remarkInjectBuiltinComponents() {
       }
     });
 
+    // Built-ins used inside the page's own code, too - JSX in an
+    // `export const Widget = () => <Icon icon="x" />` or a `{...}`
+    // expression isn't part of the content tree above, and the components
+    // map [...slug].astro passes only reaches content, so without an import
+    // `Icon` is simply undefined there. Mintlify makes its components
+    // available in both places.
+    visit(tree, ['mdxjsEsm', 'mdxFlowExpression', 'mdxTextExpression'], (node) => {
+      for (const m of String(node.value ?? '').matchAll(/<([A-Z][A-Za-z0-9]*)[\s./>]/g)) {
+        const name = m[1];
+        if (BUILTIN_COMPONENT_NAMES.includes(name) && !locallyBound.has(name)) needed.add(name);
+      }
+    });
+
     if (needed.size === 0) return;
 
     const names = [...needed].sort();