feat(docs): c15t MDX compatibility for callouts, sections, details

apps/docs-smoke/src/components/docs-mdx/callout.tsx

@@ -2,33 +2,70 @@ import type { HTMLAttributes, ReactNode } from "react";
 
 export type CalloutVariant =
   | "info"
+  | "note"
+  | "tip"
   | "warning"
   | "success"
   | "error"
   | "canary"
   | "deprecated"
   | "experimental";
 
+/**
+ * Aliases accepted by the deprecated `type` prop. Mirrors `CalloutVariant`
+ * but also accepts `"warn"` (Fumadocs-style) which maps to `"warning"`.
+ */
+export type CalloutTypeAlias = CalloutVariant | "warn";
+
 export type CalloutProps = HTMLAttributes<HTMLElement> & {
   variant?: CalloutVariant;
+  /** @deprecated Use `variant` instead. Kept for Fumadocs-authored MDX compatibility. */
+  type?: CalloutTypeAlias;
   title?: string;
   children?: ReactNode;
 };
 
-function titleCase(value: string): string {
+function normalizeVariant(
+  variant: CalloutVariant | undefined,
+  type: CalloutTypeAlias | undefined
+): CalloutVariant {
+  if (variant) {
+    return variant;
+  }
+
+  if (type === "warn") {
+    return "warning";
+  }
+
+  return type ?? "info";
+}
+
+function titleCase(value: CalloutVariant): string {
+  if (value === "canary") {
+    return "Canary";
+  }
+
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
 
 export function Callout({
-  variant = "info",
+  variant,
+  type,
   title,
   children,
   ...rest
 }: CalloutProps) {
+  const resolvedVariant = normalizeVariant(variant, type);
+
   return (
-    <aside data-inth-callout="" data-variant={variant} role="note" {...rest}>
+    <aside
+      data-inth-callout=""
+      data-variant={resolvedVariant}
+      role="note"
+      {...rest}
+    >
       <p data-inth-callout-title="">
-        <strong>{title ?? titleCase(variant)}</strong>
+        <strong>{title ?? titleCase(resolvedVariant)}</strong>
       </p>
       <div data-inth-callout-content="">{children}</div>
     </aside>

apps/docs-smoke/src/components/docs-mdx/card.tsx

@@ -12,16 +12,23 @@ export function Cards({ children, ...rest }: CardsProps) {
   );
 }
 
+export type CardVariant = "default" | "interactive";
+
 export type CardProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
   title?: string;
   description?: string;
+  icon?: ReactNode;
+  /** Known variants autocomplete; arbitrary strings still type-check for forward compat. */
+  variant?: CardVariant | (string & {});
   href?: string;
   children?: ReactNode;
 };
 
 export function Card({
   title,
   description,
+  icon,
+  variant,
   href,
   children,
   ...rest
@@ -32,11 +39,13 @@ export function Card({
   return (
     <a
       data-inth-card=""
+      data-variant={variant ?? undefined}
       href={href}
       rel={isExternal ? "noopener" : undefined}
       target={isExternal ? "_blank" : undefined}
       {...rest}
     >
+      {icon ? <span data-inth-card-icon="">{icon}</span> : null}
       {title ? <h3 data-inth-card-title="">{title}</h3> : null}
       {description ? <p data-inth-card-description="">{description}</p> : null}
       {children}

apps/docs-smoke/src/components/docs-mdx/tabs.tsx

@@ -18,6 +18,8 @@ interface TabsContextValue {
 }
 
 const TabsContext = createContext<TabsContextValue | null>(null);
+const ID_TOKEN_UNSAFE_CHARACTER_PATTERN = /[^A-Za-z0-9_-]/g;
+const ID_TOKEN_WHITESPACE_PATTERN = /\s+/g;
 
 function useTabsContext(): TabsContextValue {
   const ctx = useContext(TabsContext);
@@ -31,6 +33,27 @@ function normalize(value: string): string {
   return value.toLowerCase().replace(/\s+/g, "-");
 }
 
+function normalizeIdToken(value: string): string {
+  return value
+    .trim()
+    .replace(ID_TOKEN_WHITESPACE_PATTERN, "-")
+    .replace(ID_TOKEN_UNSAFE_CHARACTER_PATTERN, "");
+}
+
+function resolveGroupId(
+  providedGroupId: unknown,
+  generatedGroupId: string
+): string {
+  if (typeof providedGroupId === "string") {
+    const normalizedProvidedGroupId = normalizeIdToken(providedGroupId);
+    if (normalizedProvidedGroupId) {
+      return normalizedProvidedGroupId;
+    }
+  }
+
+  return normalizeIdToken(generatedGroupId) || "tabs";
+}
+
 /**
  * Build a stable id for a tab given its index. We include the index so two
  * items that normalize to the same string (e.g. "Tab 1" and "tab 1") still
@@ -47,13 +70,26 @@ function panelId(groupId: string, normalized: string, index: number): string {
 export interface TabsProps {
   children?: ReactNode;
   defaultIndex?: number;
+  /**
+   * Stable id used to derive trigger/panel DOM ids. Useful for SSR-stable
+   * markup. Must be unique per page — duplicate `groupId`s will produce
+   * duplicate `aria-controls`/`id` attributes. This does NOT sync state
+   * across multiple `<Tabs>` instances.
+   */
+  groupId?: string;
   items?: string[];
 }
 
-export function Tabs({ items = [], defaultIndex = 0, children }: TabsProps) {
+export function Tabs({
+  items = [],
+  defaultIndex = 0,
+  groupId: providedGroupId,
+  children,
+}: TabsProps) {
   const initial = items[defaultIndex] ?? items[0] ?? "";
   const [activeValue, setActiveValue] = useState(normalize(initial));
-  const groupId = useId();
+  const generatedGroupId = useId();
+  const groupId = resolveGroupId(providedGroupId, generatedGroupId);
 
   const value = useMemo<TabsContextValue>(
     () => ({ items, activeValue, setActiveValue, groupId }),

packages/docs/src/remark/index.ts

@@ -1,24 +1,6 @@
 /** @biome-ignore lint/performance/noBarrelFile: package entry point */
 
-export * from "./libs";
-export { remarkAccordionToMarkdown } from "./plugins/accordion.remark";
-export { remarkCalloutToMarkdown } from "./plugins/callout.remark";
-export { remarkCardsToMarkdown } from "./plugins/cards.remark";
-export { remarkCommandTabsToMarkdown } from "./plugins/command-tabs.remark";
-export { remarkResolveDocPlaceholders } from "./plugins/doc-placeholders.remark";
-export { remarkExampleToMarkdown } from "./plugins/example.remark";
 export { remarkInclude } from "./plugins/include.remark";
-export { remarkLinkIcon } from "./plugins/link-icon.remark";
-export { remarkMermaidToMarkdown } from "./plugins/mermaid.remark";
-export { remarkRemoveImports } from "./plugins/remove-imports.remark";
-export { remarkStepsToMarkdown } from "./plugins/steps.remark";
-export { remarkTabsToMarkdown } from "./plugins/tabs.remark";
-export {
-  extractTocFromContent,
-  extractTocFromFile,
-  type TOCItem,
-} from "./plugins/toc-extract.remark";
-export { remarkTopicSwitcherToMarkdown } from "./plugins/topic-switcher.remark";
 export {
   extractTypeFromFile,
   remarkTypeTableToMarkdown,
@@ -28,10 +10,13 @@ import { remarkAccordionToMarkdown } from "./plugins/accordion.remark";
 import { remarkCalloutToMarkdown } from "./plugins/callout.remark";
 import { remarkCardsToMarkdown } from "./plugins/cards.remark";
 import { remarkCommandTabsToMarkdown } from "./plugins/command-tabs.remark";
+import { remarkDetailsToMarkdown } from "./plugins/details.remark";
 import { remarkResolveDocPlaceholders } from "./plugins/doc-placeholders.remark";
 import { remarkExampleToMarkdown } from "./plugins/example.remark";
 import { remarkMermaidToMarkdown } from "./plugins/mermaid.remark";
 import { remarkRemoveImports } from "./plugins/remove-imports.remark";
+import { remarkRemoveJsxComments } from "./plugins/remove-jsx-comments.remark";
+import { remarkSectionToMarkdown } from "./plugins/section.remark";
 import { remarkStepsToMarkdown } from "./plugins/steps.remark";
 import { remarkTabsToMarkdown } from "./plugins/tabs.remark";
 import { remarkTopicSwitcherToMarkdown } from "./plugins/topic-switcher.remark";
@@ -44,9 +29,12 @@ import { remarkTypeTableToMarkdown } from "./plugins/type-table.remark";
  */
 export const defaultRemarkPlugins = [
   remarkRemoveImports,
+  remarkRemoveJsxComments,
   remarkResolveDocPlaceholders,
+  remarkSectionToMarkdown,
   remarkCalloutToMarkdown,
   remarkCardsToMarkdown,
+  remarkDetailsToMarkdown,
   remarkMermaidToMarkdown,
   remarkCommandTabsToMarkdown,
   remarkStepsToMarkdown,

packages/docs/src/remark/plugins/callout.remark.ts

@@ -35,8 +35,11 @@ function variantLabelAndEmoji(raw: string | null): {
 } {
   const v = (raw ?? "info").toLowerCase();
   switch (v) {
+    case "warn":
     case "warning":
       return { variant: "warning", emoji: "⚠️", label: "Warning:" };
+    case "note":
+      return { variant: "note", emoji: "📝", label: "Note:" };
     case "tip":
       return { variant: "tip", emoji: "💡", label: "Tip:" };
     case "success":

packages/docs/src/remark/plugins/details.remark.ts

@@ -0,0 +1,62 @@
+import type { Root, RootContent } from "mdast";
+import type { Transformer } from "unified";
+import {
+  createHeading,
+  createJsxComponentProcessor,
+  extractNodeText,
+  hasName,
+  type MdxNode,
+} from "../libs";
+
+function extractSummary(child: RootContent): string | null {
+  if (hasName(child, "summary")) {
+    const extracted = extractNodeText(child.children).trim();
+    return extracted.length > 0 ? extracted : null;
+  }
+
+  // MDX sometimes parses `<summary>...</summary>` (when followed by a blank
+  // line) as a paragraph whose only child is the JSX element. Unwrap that.
+  if (child.type !== "paragraph") {
+    return null;
+  }
+
+  const [firstChild] = child.children;
+  if (!(firstChild && hasName(firstChild, "summary"))) {
+    return null;
+  }
+
+  const extracted = extractNodeText(firstChild.children).trim();
+  return extracted.length > 0 ? extracted : null;
+}
+
+function toDetailsContent(node: MdxNode): RootContent[] {
+  const content: RootContent[] = [];
+  let summaryText: string | null = null;
+
+  for (const child of node.children ?? []) {
+    const extractedSummary = extractSummary(child as RootContent);
+    if (extractedSummary) {
+      summaryText = extractedSummary;
+      continue;
+    }
+
+    content.push(child as RootContent);
+  }
+
+  if (summaryText) {
+    return [createHeading(3, summaryText), ...content];
+  }
+
+  // Fallback heading so collapsible bodies don't appear as orphan content.
+  if (content.length > 0) {
+    return [createHeading(3, "Details"), ...content];
+  }
+
+  return content;
+}
+
+export function remarkDetailsToMarkdown(): Transformer<Root, Root> {
+  return createJsxComponentProcessor("details", (node) =>
+    toDetailsContent(node)
+  );
+}

packages/docs/src/remark/plugins/remove-jsx-comments.remark.ts

@@ -0,0 +1,33 @@
+import type { Root } from "mdast";
+import type { Transformer } from "unified";
+import { visit } from "unist-util-visit";
+
+function isJsxComment(value: unknown): boolean {
+  return (
+    typeof value === "string" &&
+    value.trim().startsWith("/*") &&
+    value.trim().endsWith("*/")
+  );
+}
+
+export function remarkRemoveJsxComments(): Transformer<Root, Root> {
+  return (tree) => {
+    visit(
+      tree,
+      ["mdxFlowExpression", "mdxTextExpression"],
+      (node, index, parent) => {
+        if (!parent || typeof index !== "number") {
+          return;
+        }
+
+        if (!isJsxComment((node as { value?: unknown }).value)) {
+          return;
+        }
+
+        parent.children.splice(index, 1);
+        // Re-visit at the same index so adjacent comments are also removed.
+        return index;
+      }
+    );
+  };
+}

packages/docs/src/remark/plugins/section.remark.ts

@@ -0,0 +1,29 @@
+import type { Root, RootContent } from "mdast";
+import type { Transformer } from "unified";
+import { visit } from "unist-util-visit";
+import { hasName } from "../libs";
+
+export function remarkSectionToMarkdown(): Transformer<Root, Root> {
+  return (tree) => {
+    visit(
+      tree,
+      ["mdxJsxFlowElement", "mdxJsxTextElement"],
+      (node, index, parent) => {
+        if (!parent || typeof index !== "number" || !hasName(node, "section")) {
+          return;
+        }
+
+        // Section attributes (e.g. `id="types"`) are intentionally dropped —
+        // this output is consumed by LLMs/llms.txt, not browsers that resolve anchors.
+        parent.children.splice(
+          index,
+          1,
+          ...((node.children as RootContent[] | undefined) ?? [])
+        );
+
+        // Re-visit at the same index so nested <section> wrappers also unwrap.
+        return index;
+      }
+    );
+  };
+}