From d289d829d885ca4713178df6b2f736f59e751dfb Mon Sep 17 00:00:00 2001
From: Kaylee <65376239+KayleeWilliams@users.noreply.github.com>
Date: Sat, 25 Apr 2026 17:04:57 -0400
Subject: [PATCH 1/3] feat(docs): add c15t MDX compatibility for callouts,
 sections, details
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make @inth/docs a drop-in target for Fumadocs-style MDX (used by c15t)
without forking. Adds three remark plugins (section unwrap, details
flatten, JSX-comment strip), accepts <Callout type="warn"|"note">
aliases, gives PackageCommandTabs a `mode` prop, gives Tabs a `groupId`,
adds icon/variant props on Card. Extracts COMMANDS and resolveCommand to
internal/ so component and remark plugin share one source of truth, and
fixes a unist-util-visit splice-resume bug that previously skipped
nested <section> wrappers and adjacent JSX comments.

Tests: 14 new (logic + edge cases). Smoke pipeline against the c15t
fixture passes (200/200 .mdx → .md).
---
 packages/docs/src/components/callout.tsx      |  38 +++--
 packages/docs/src/components/card.tsx         |   9 ++
 packages/docs/src/components/index.ts         |  10 +-
 .../src/components/package-command-tabs.tsx   |  33 ++---
 packages/docs/src/components/tabs.tsx         |  17 ++-
 .../docs/src/internal/callout-variant.test.ts |  40 +++++
 packages/docs/src/internal/callout-variant.ts |  42 ++++++
 .../src/internal/package-managers.test.ts     |  56 +++++++
 .../docs/src/internal/package-managers.ts     |  53 +++++++
 packages/docs/src/remark/index.ts             |   9 ++
 .../docs/src/remark/plugins/callout.remark.ts |   3 +
 .../docs/src/remark/plugins/details.remark.ts |  62 ++++++++
 .../plugins/package-command-tabs.remark.ts    |  28 +---
 .../plugins/remove-jsx-comments.remark.ts     |  33 +++++
 .../docs/src/remark/plugins/section.remark.ts |  29 ++++
 .../docs/src/remark/remark-output.test.ts     | 138 ++++++++++++++++++
 16 files changed, 541 insertions(+), 59 deletions(-)
 create mode 100644 packages/docs/src/internal/callout-variant.test.ts
 create mode 100644 packages/docs/src/internal/callout-variant.ts
 create mode 100644 packages/docs/src/internal/package-managers.test.ts
 create mode 100644 packages/docs/src/internal/package-managers.ts
 create mode 100644 packages/docs/src/remark/plugins/details.remark.ts
 create mode 100644 packages/docs/src/remark/plugins/remove-jsx-comments.remark.ts
 create mode 100644 packages/docs/src/remark/plugins/section.remark.ts

diff --git a/packages/docs/src/components/callout.tsx b/packages/docs/src/components/callout.tsx
index 1d30383..e6b8f60 100644
--- a/packages/docs/src/components/callout.tsx
+++ b/packages/docs/src/components/callout.tsx
@@ -1,34 +1,42 @@
 import type { HTMLAttributes, ReactNode } from "react";
+import {
+  type CalloutTypeAlias,
+  type CalloutVariant,
+  calloutTitleCase,
+  normalizeCalloutVariant,
+} from "../internal/callout-variant";
 
-export type CalloutVariant =
-  | "info"
-  | "warning"
-  | "success"
-  | "error"
-  | "canary"
-  | "deprecated"
-  | "experimental";
+export type {
+  CalloutTypeAlias,
+  CalloutVariant,
+} from "../internal/callout-variant";
 
 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 {
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}
-
 export function Callout({
-  variant = "info",
+  variant,
+  type,
   title,
   children,
   ...rest
 }: CalloutProps) {
+  const resolvedVariant = normalizeCalloutVariant(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 ?? calloutTitleCase(resolvedVariant)}</strong>
       </p>
       <div data-inth-callout-content="">{children}</div>
     </aside>
diff --git a/packages/docs/src/components/card.tsx b/packages/docs/src/components/card.tsx
index c6955ef..4edad07 100644
--- a/packages/docs/src/components/card.tsx
+++ b/packages/docs/src/components/card.tsx
@@ -12,9 +12,14 @@ 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;
 };
@@ -22,6 +27,8 @@ export type CardProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
 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}
diff --git a/packages/docs/src/components/index.ts b/packages/docs/src/components/index.ts
index 31106ab..e8b6f0a 100644
--- a/packages/docs/src/components/index.ts
+++ b/packages/docs/src/components/index.ts
@@ -3,15 +3,23 @@
 export {
   Callout,
   type CalloutProps,
+  type CalloutTypeAlias,
   type CalloutVariant,
 } from "./callout";
-export { Card, type CardProps, Cards, type CardsProps } from "./card";
+export {
+  Card,
+  type CardProps,
+  Cards,
+  type CardsProps,
+  type CardVariant,
+} from "./card";
 export {
   type MdxComponents,
   mdxComponents,
 } from "./mdx-components";
 export { Mermaid, type MermaidProps } from "./mermaid";
 export {
+  type PackageCommandMode,
   PackageCommandTabs,
   type PackageCommandTabsProps,
   type PackageManager,
diff --git a/packages/docs/src/components/package-command-tabs.tsx b/packages/docs/src/components/package-command-tabs.tsx
index 7123931..9300940 100644
--- a/packages/docs/src/components/package-command-tabs.tsx
+++ b/packages/docs/src/components/package-command-tabs.tsx
@@ -1,10 +1,17 @@
 "use client";
 
 import { type ReactNode, useState } from "react";
+import {
+  MANAGERS,
+  type PackageCommandMode,
+  type PackageManager,
+  resolvePackageCommand,
+} from "../internal/package-managers";
 
-// Single source of truth — derive the union type from the tuple.
-const MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
-export type PackageManager = (typeof MANAGERS)[number];
+export type {
+  PackageCommandMode,
+  PackageManager,
+} from "../internal/package-managers";
 
 export type PackageCommandTabsProps = {
   /** Command template — `{pm}` is replaced with the active package manager. E.g. "{pm} install @inth/docs" */
@@ -12,33 +19,19 @@ export type PackageCommandTabsProps = {
   /** Or pass pre-rendered commands per manager */
   commands?: Partial<Record<PackageManager, string>>;
   defaultManager?: PackageManager;
+  mode?: PackageCommandMode;
   children?: ReactNode;
 };
 
-function resolveCommand(
-  manager: PackageManager,
-  command: string | undefined,
-  commands: Partial<Record<PackageManager, string>> | undefined
-): string {
-  // Presence check so an explicit "" override wins over the template fallback.
-  const explicit = commands?.[manager];
-  if (explicit !== undefined) {
-    return explicit;
-  }
-  if (command) {
-    return command.replaceAll("{pm}", manager);
-  }
-  return "";
-}
-
 export function PackageCommandTabs({
   command,
   commands,
   defaultManager = "npm",
+  mode = "run",
   children,
 }: PackageCommandTabsProps) {
   const [active, setActive] = useState<PackageManager>(defaultManager);
-  const resolved = resolveCommand(active, command, commands);
+  const resolved = resolvePackageCommand(active, command, commands, mode);
 
   return (
     <div data-inth-package-command-tabs="">
diff --git a/packages/docs/src/components/tabs.tsx b/packages/docs/src/components/tabs.tsx
index 1953ce7..a5125c5 100644
--- a/packages/docs/src/components/tabs.tsx
+++ b/packages/docs/src/components/tabs.tsx
@@ -47,13 +47,26 @@ function panelId(groupId: string, normalized: string, index: number): string {
 export type TabsProps = {
   items?: string[];
   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;
   children?: ReactNode;
 };
 
-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 = providedGroupId ?? generatedGroupId;
 
   const value = useMemo<TabsContextValue>(
     () => ({ items, activeValue, setActiveValue, groupId }),
diff --git a/packages/docs/src/internal/callout-variant.test.ts b/packages/docs/src/internal/callout-variant.test.ts
new file mode 100644
index 0000000..f540991
--- /dev/null
+++ b/packages/docs/src/internal/callout-variant.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { calloutTitleCase, normalizeCalloutVariant } from "./callout-variant";
+
+describe("normalizeCalloutVariant", () => {
+  it("returns the explicit variant when set", () => {
+    expect(normalizeCalloutVariant("warning", undefined)).toBe("warning");
+    expect(normalizeCalloutVariant("note", undefined)).toBe("note");
+  });
+
+  it("variant takes precedence over the legacy type prop", () => {
+    expect(normalizeCalloutVariant("info", "warn")).toBe("info");
+    expect(normalizeCalloutVariant("error", "tip")).toBe("error");
+  });
+
+  it("maps the Fumadocs `warn` alias to `warning`", () => {
+    expect(normalizeCalloutVariant(undefined, "warn")).toBe("warning");
+  });
+
+  it("passes through other legacy type values unchanged", () => {
+    expect(normalizeCalloutVariant(undefined, "note")).toBe("note");
+    expect(normalizeCalloutVariant(undefined, "tip")).toBe("tip");
+    expect(normalizeCalloutVariant(undefined, "canary")).toBe("canary");
+  });
+
+  it("defaults to `info` when both inputs are undefined", () => {
+    expect(normalizeCalloutVariant(undefined, undefined)).toBe("info");
+  });
+});
+
+describe("calloutTitleCase", () => {
+  it("title-cases standard variants", () => {
+    expect(calloutTitleCase("info")).toBe("Info");
+    expect(calloutTitleCase("warning")).toBe("Warning");
+    expect(calloutTitleCase("deprecated")).toBe("Deprecated");
+  });
+
+  it("preserves `Canary` (already title-cased word in the brand)", () => {
+    expect(calloutTitleCase("canary")).toBe("Canary");
+  });
+});
diff --git a/packages/docs/src/internal/callout-variant.ts b/packages/docs/src/internal/callout-variant.ts
new file mode 100644
index 0000000..716cfe3
--- /dev/null
+++ b/packages/docs/src/internal/callout-variant.ts
@@ -0,0 +1,42 @@
+// Pure variant resolution for the Callout component. Lives in `internal/`
+// so it can be unit-tested without rendering 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 function normalizeCalloutVariant(
+  variant: CalloutVariant | undefined,
+  type: CalloutTypeAlias | undefined
+): CalloutVariant {
+  if (variant) {
+    return variant;
+  }
+
+  if (type === "warn") {
+    return "warning";
+  }
+
+  return type ?? "info";
+}
+
+export function calloutTitleCase(value: CalloutVariant): string {
+  if (value === "canary") {
+    return "Canary";
+  }
+
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
diff --git a/packages/docs/src/internal/package-managers.test.ts b/packages/docs/src/internal/package-managers.test.ts
new file mode 100644
index 0000000..5972da8
--- /dev/null
+++ b/packages/docs/src/internal/package-managers.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { COMMANDS, MANAGERS, resolvePackageCommand } from "./package-managers";
+
+describe("resolvePackageCommand", () => {
+  it("renders the run-mode template for a bare command", () => {
+    expect(resolvePackageCommand("npm", "@inth/docs", undefined, "run")).toBe(
+      "npx @inth/docs"
+    );
+    expect(resolvePackageCommand("bun", "@inth/docs", undefined, "run")).toBe(
+      "bunx @inth/docs"
+    );
+  });
+
+  it("renders the install-mode template for a bare command", () => {
+    expect(
+      resolvePackageCommand("npm", "@inth/docs", undefined, "install")
+    ).toBe("npm install @inth/docs");
+    expect(
+      resolvePackageCommand("pnpm", "@inth/docs", undefined, "install")
+    ).toBe("pnpm add @inth/docs");
+  });
+
+  it("substitutes a `{pm}` placeholder when present (legacy path)", () => {
+    expect(
+      resolvePackageCommand("yarn", "{pm} install @inth/docs", undefined, "run")
+    ).toBe("yarn install @inth/docs");
+  });
+
+  it("explicit per-manager overrides win over the template", () => {
+    const overrides = { npm: "npm install @inth/docs --legacy-peer-deps" };
+    expect(
+      resolvePackageCommand("npm", "@inth/docs", overrides, "install")
+    ).toBe("npm install @inth/docs --legacy-peer-deps");
+  });
+
+  it("respects an empty-string override (suppresses output)", () => {
+    expect(
+      resolvePackageCommand("yarn", "@inth/docs", { yarn: "" }, "run")
+    ).toBe("");
+  });
+
+  it("returns empty string when no command and no override is supplied", () => {
+    expect(resolvePackageCommand("npm", undefined, undefined, "run")).toBe("");
+  });
+});
+
+describe("MANAGERS / COMMANDS shape", () => {
+  it("declares one template per manager in each mode", () => {
+    for (const mode of ["run", "install"] as const) {
+      for (const manager of MANAGERS) {
+        const template = COMMANDS[mode][manager];
+        expect(template).toContain("{pkg}");
+      }
+    }
+  });
+});
diff --git a/packages/docs/src/internal/package-managers.ts b/packages/docs/src/internal/package-managers.ts
new file mode 100644
index 0000000..01e9d5e
--- /dev/null
+++ b/packages/docs/src/internal/package-managers.ts
@@ -0,0 +1,53 @@
+// Single source of truth for package-manager command templates.
+// Imported by both the React component (`components/package-command-tabs.tsx`)
+// and the remark plugin (`remark/plugins/package-command-tabs.remark.ts`).
+
+export const MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+export type PackageManager = (typeof MANAGERS)[number];
+
+export type PackageCommandMode = "run" | "install";
+
+export const COMMANDS: Record<
+  PackageCommandMode,
+  Record<PackageManager, string>
+> = {
+  install: {
+    npm: "npm install {pkg}",
+    pnpm: "pnpm add {pkg}",
+    yarn: "yarn add {pkg}",
+    bun: "bun add {pkg}",
+  },
+  run: {
+    npm: "npx {pkg}",
+    pnpm: "pnpm dlx {pkg}",
+    yarn: "yarn dlx {pkg}",
+    bun: "bunx {pkg}",
+  },
+};
+
+/**
+ * Resolve the rendered command for a single package manager. Three precedence
+ * rules:
+ *   1. An explicit `commands[manager]` override wins (including `""` to suppress).
+ *   2. A `command` template containing `{pm}` is treated as a literal template.
+ *   3. Otherwise `command` is treated as a package/CLI name and expanded via
+ *      `COMMANDS[mode][manager]`.
+ */
+export function resolvePackageCommand(
+  manager: PackageManager,
+  command: string | undefined,
+  commands: Partial<Record<PackageManager, string>> | undefined,
+  mode: PackageCommandMode
+): string {
+  const explicit = commands?.[manager];
+  if (explicit !== undefined) {
+    return explicit;
+  }
+  if (command) {
+    if (command.includes("{pm}")) {
+      return command.replaceAll("{pm}", manager);
+    }
+    return COMMANDS[mode][manager].replace("{pkg}", command);
+  }
+  return "";
+}
diff --git a/packages/docs/src/remark/index.ts b/packages/docs/src/remark/index.ts
index d2b2ddc..f173128 100644
--- a/packages/docs/src/remark/index.ts
+++ b/packages/docs/src/remark/index.ts
@@ -3,12 +3,15 @@
 export * from "./libs";
 export { remarkCalloutToMarkdown } from "./plugins/callout.remark";
 export { remarkCardsToMarkdown } from "./plugins/cards.remark";
+export { remarkDetailsToMarkdown } from "./plugins/details.remark";
 export { remarkResolveDocPlaceholders } from "./plugins/doc-placeholders.remark";
 export { remarkInclude } from "./plugins/include.remark";
 export { remarkLinkIcon } from "./plugins/link-icon.remark";
 export { remarkMermaidToMarkdown } from "./plugins/mermaid.remark";
 export { remarkPackageCommandTabsToMarkdown } from "./plugins/package-command-tabs.remark";
 export { remarkRemoveImports } from "./plugins/remove-imports.remark";
+export { remarkRemoveJsxComments } from "./plugins/remove-jsx-comments.remark";
+export { remarkSectionToMarkdown } from "./plugins/section.remark";
 export { remarkStepsToMarkdown } from "./plugins/steps.remark";
 export { remarkTabsToMarkdown } from "./plugins/tabs.remark";
 export {
@@ -23,10 +26,13 @@ export {
 
 import { remarkCalloutToMarkdown } from "./plugins/callout.remark";
 import { remarkCardsToMarkdown } from "./plugins/cards.remark";
+import { remarkDetailsToMarkdown } from "./plugins/details.remark";
 import { remarkResolveDocPlaceholders } from "./plugins/doc-placeholders.remark";
 import { remarkMermaidToMarkdown } from "./plugins/mermaid.remark";
 import { remarkPackageCommandTabsToMarkdown } from "./plugins/package-command-tabs.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 { remarkTypeTableToMarkdown } from "./plugins/type-table.remark";
@@ -38,9 +44,12 @@ import { remarkTypeTableToMarkdown } from "./plugins/type-table.remark";
  */
 export const defaultRemarkPlugins = [
   remarkRemoveImports,
+  remarkRemoveJsxComments,
   remarkResolveDocPlaceholders,
+  remarkSectionToMarkdown,
   remarkCalloutToMarkdown,
   remarkCardsToMarkdown,
+  remarkDetailsToMarkdown,
   remarkMermaidToMarkdown,
   remarkPackageCommandTabsToMarkdown,
   remarkStepsToMarkdown,
diff --git a/packages/docs/src/remark/plugins/callout.remark.ts b/packages/docs/src/remark/plugins/callout.remark.ts
index 4dd585f..47ffce0 100644
--- a/packages/docs/src/remark/plugins/callout.remark.ts
+++ b/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":
diff --git a/packages/docs/src/remark/plugins/details.remark.ts b/packages/docs/src/remark/plugins/details.remark.ts
new file mode 100644
index 0000000..8f68dd5
--- /dev/null
+++ b/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)
+  );
+}
diff --git a/packages/docs/src/remark/plugins/package-command-tabs.remark.ts b/packages/docs/src/remark/plugins/package-command-tabs.remark.ts
index aaa7998..5578c0d 100644
--- a/packages/docs/src/remark/plugins/package-command-tabs.remark.ts
+++ b/packages/docs/src/remark/plugins/package-command-tabs.remark.ts
@@ -2,6 +2,12 @@
 /** @biome-ignore lint/nursery/noUnnecessaryConditions: these are packages */
 import type { Root } from "mdast";
 import type { Transformer } from "unified";
+import {
+  COMMANDS,
+  MANAGERS as DEFAULT_MANAGERS,
+  type PackageCommandMode as Mode,
+  type PackageManager as Pm,
+} from "../../internal/package-managers";
 import {
   createInlineCode,
   createJsxComponentProcessor,
@@ -9,34 +15,14 @@ import {
   getAttributeValue,
 } from "../libs";
 
-type Mode = "run" | "install";
-
 type Options = {
   /** Column labels. */
   labels?: { pm?: string; command?: string };
   /** Which package managers to include and in what order. */
-  managers?: Array<"npm" | "pnpm" | "yarn" | "bun">;
+  managers?: Pm[];
 };
 
 const DEFAULT_LABELS = { pm: "Package manager", command: "Command" } as const;
-const DEFAULT_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
-
-const COMMANDS = {
-  install: {
-    npm: "npm install {pkg}",
-    pnpm: "pnpm add {pkg}",
-    yarn: "yarn add {pkg}",
-    bun: "bun add {pkg}",
-  },
-  run: {
-    npm: "npx {pkg}",
-    pnpm: "pnpm dlx {pkg}",
-    yarn: "yarn dlx {pkg}",
-    bun: "bunx {pkg}",
-  },
-} as const;
-
-type Pm = keyof (typeof COMMANDS)["run"];
 
 function cmdsFor(pm: Pm, pkgCmd: string, mode: Mode): string {
   const template = COMMANDS[mode][pm];
diff --git a/packages/docs/src/remark/plugins/remove-jsx-comments.remark.ts b/packages/docs/src/remark/plugins/remove-jsx-comments.remark.ts
new file mode 100644
index 0000000..5a0bc85
--- /dev/null
+++ b/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;
+      }
+    );
+  };
+}
diff --git a/packages/docs/src/remark/plugins/section.remark.ts b/packages/docs/src/remark/plugins/section.remark.ts
new file mode 100644
index 0000000..2325136
--- /dev/null
+++ b/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;
+      }
+    );
+  };
+}
diff --git a/packages/docs/src/remark/remark-output.test.ts b/packages/docs/src/remark/remark-output.test.ts
index 5a50cd0..b365c56 100644
--- a/packages/docs/src/remark/remark-output.test.ts
+++ b/packages/docs/src/remark/remark-output.test.ts
@@ -102,6 +102,23 @@ describe("remark markdown output", () => {
     );
   });
 
+  it("supports c15t callout aliases for warn and note", async () => {
+    const sourcePath = await createTempMdxFile(
+      "callouts.mdx",
+      `<Callout type="warn">Be careful.</Callout>
+
+<Callout type="note">Background detail.</Callout>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("> ⚠️ **Warning:**");
+    expect(result.markdown).toContain("> 📝 **Note:**");
+    expect(result.markdown).toContain("Be careful.");
+    expect(result.markdown).toContain("Background detail.");
+  });
+
   it("synthesizes section titles for index files", async () => {
     const sourcePath = await createTempMdxFile(
       path.join("frameworks", "index.mdx"),
@@ -176,4 +193,125 @@ Body
     expect(result.markdown).toContain("publishedAt: 2026-04-19T00:00:00.000Z");
     expect(result.markdown).toContain("url: /docs/frameworks/next/quickstart");
   });
+
+  it("removes JSX comments, unwraps sections, and flattens details blocks", async () => {
+    const sourcePath = await createTempMdxFile(
+      path.join("shared", "overview.mdx"),
+      `{/* This file is NOT rendered directly. */}
+
+<section id="types">
+  Intro copy.
+
+  <details>
+    <summary>\`ConsentState\`</summary>
+
+    More detail here.
+  </details>
+</section>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("description: Intro copy.");
+    expect(result.markdown).toContain("Intro copy.");
+    expect(result.markdown).toContain("### ConsentState");
+    expect(result.markdown).toContain("More detail here.");
+    expect(result.markdown).not.toContain("{/*");
+    expect(result.markdown).not.toContain("<section");
+    expect(result.markdown).not.toContain("<details>");
+    expect(result.markdown).not.toContain("<summary>");
+  });
+
+  it("falls back to a generic heading when <details> has no <summary>", async () => {
+    const sourcePath = await createTempMdxFile(
+      "details-no-summary.mdx",
+      `<details>
+  Body without a summary.
+</details>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("### Details");
+    expect(result.markdown).toContain("Body without a summary.");
+    expect(result.markdown).not.toContain("<details>");
+  });
+
+  it("extracts a <summary> that MDX parses inside a paragraph wrapper", async () => {
+    // When <summary>...</summary> is followed by a blank line, MDX wraps the
+    // JSX element in a paragraph. The plugin needs to unwrap that.
+    const sourcePath = await createTempMdxFile(
+      "details-paragraph-summary.mdx",
+      `<details>
+  <summary>Wrapped Summary</summary>
+
+  Body text.
+</details>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("### Wrapped Summary");
+    expect(result.markdown).toContain("Body text.");
+  });
+
+  it("removes adjacent JSX comments in a single pass", async () => {
+    const sourcePath = await createTempMdxFile(
+      "adjacent-comments.mdx",
+      `{/* first */}
+{/* second */}
+{/* third */}
+
+Body copy.
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).not.toContain("first");
+    expect(result.markdown).not.toContain("second");
+    expect(result.markdown).not.toContain("third");
+    expect(result.markdown).not.toContain("{/*");
+    expect(result.markdown).toContain("Body copy.");
+  });
+
+  it("unwraps nested <section> blocks (regression for visit() splice resume)", async () => {
+    const sourcePath = await createTempMdxFile(
+      "nested-sections.mdx",
+      `<section id="outer">
+  Outer copy.
+
+  <section id="inner">
+    Inner copy.
+  </section>
+</section>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("Outer copy.");
+    expect(result.markdown).toContain("Inner copy.");
+    expect(result.markdown).not.toContain("<section");
+  });
+
+  it("drops <section> attributes silently (id is not preserved)", async () => {
+    const sourcePath = await createTempMdxFile(
+      "section-with-id.mdx",
+      `<section id="types" className="anchor">
+  Anchor body.
+</section>
+`
+    );
+
+    const result = await convertMdxFile(sourcePath, defaultRemarkPlugins);
+
+    expect(result.markdown).toContain("Anchor body.");
+    expect(result.markdown).not.toContain('id="types"');
+    expect(result.markdown).not.toContain("anchor");
+    expect(result.markdown).not.toContain("<section");
+  });
 });

From 7d35cf43817a90e2db398b98243af6fb468f8013 Mon Sep 17 00:00:00 2001
From: Kaylee <65376239+KayleeWilliams@users.noreply.github.com>
Date: Sun, 26 Apr 2026 23:50:19 -0700
Subject: [PATCH 2/3] Address docs review feedback

---
 .../src/components/docs-mdx/index.ts          |  9 +------
 .../src/components/docs-mdx/tabs.tsx          | 25 ++++++++++++++++++-
 packages/docs/src/remark/index.ts             | 21 ----------------
 3 files changed, 25 insertions(+), 30 deletions(-)

diff --git a/apps/docs-smoke/src/components/docs-mdx/index.ts b/apps/docs-smoke/src/components/docs-mdx/index.ts
index 40295e1..09d5080 100644
--- a/apps/docs-smoke/src/components/docs-mdx/index.ts
+++ b/apps/docs-smoke/src/components/docs-mdx/index.ts
@@ -8,16 +8,9 @@ export {
 export {
   Callout,
   type CalloutProps,
-  type CalloutTypeAlias,
   type CalloutVariant,
 } from "./callout";
-export {
-  Card,
-  type CardProps,
-  Cards,
-  type CardsProps,
-  type CardVariant,
-} from "./card";
+export { Card, type CardProps, Cards, type CardsProps } from "./card";
 export {
   type CommandMode,
   CommandTabs,
diff --git a/apps/docs-smoke/src/components/docs-mdx/tabs.tsx b/apps/docs-smoke/src/components/docs-mdx/tabs.tsx
index 1c129da..d0bed4a 100644
--- a/apps/docs-smoke/src/components/docs-mdx/tabs.tsx
+++ b/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: string | undefined,
+  generatedGroupId: string
+): string {
+  if (providedGroupId !== undefined) {
+    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
@@ -66,7 +89,7 @@ export function Tabs({
   const initial = items[defaultIndex] ?? items[0] ?? "";
   const [activeValue, setActiveValue] = useState(normalize(initial));
   const generatedGroupId = useId();
-  const groupId = providedGroupId ?? generatedGroupId;
+  const groupId = resolveGroupId(providedGroupId, generatedGroupId);
 
   const value = useMemo<TabsContextValue>(
     () => ({ items, activeValue, setActiveValue, groupId }),
diff --git a/packages/docs/src/remark/index.ts b/packages/docs/src/remark/index.ts
index 0e5eea3..06b2d86 100644
--- a/packages/docs/src/remark/index.ts
+++ b/packages/docs/src/remark/index.ts
@@ -1,27 +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 { remarkDetailsToMarkdown } from "./plugins/details.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 { remarkRemoveJsxComments } from "./plugins/remove-jsx-comments.remark";
-export { remarkSectionToMarkdown } from "./plugins/section.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,

From c7d0e46505a836839a6de5ff6da8b9ff5a0193a0 Mon Sep 17 00:00:00 2001
From: Kaylee <65376239+KayleeWilliams@users.noreply.github.com>
Date: Mon, 27 Apr 2026 10:07:06 -0700
Subject: [PATCH 3/3] Harden tabs group id handling

---
 apps/docs-smoke/src/components/docs-mdx/tabs.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs-smoke/src/components/docs-mdx/tabs.tsx b/apps/docs-smoke/src/components/docs-mdx/tabs.tsx
index d0bed4a..7caf55a 100644
--- a/apps/docs-smoke/src/components/docs-mdx/tabs.tsx
+++ b/apps/docs-smoke/src/components/docs-mdx/tabs.tsx
@@ -41,10 +41,10 @@ function normalizeIdToken(value: string): string {
 }
 
 function resolveGroupId(
-  providedGroupId: string | undefined,
+  providedGroupId: unknown,
   generatedGroupId: string
 ): string {
-  if (providedGroupId !== undefined) {
+  if (typeof providedGroupId === "string") {
     const normalizedProvidedGroupId = normalizeIdToken(providedGroupId);
     if (normalizedProvidedGroupId) {
       return normalizedProvidedGroupId;