reallysimpledocs 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -61,6 +61,16 @@ Welcome to the docs.
 
 RSD injects docs pages, Lunr search, per-page Markdown exports, `llms.txt`, and `llms-full.txt`.
 
+Use `.md` for normal pages and `.mdx` when a page needs Astro components:
+
+```mdx
+import { Callout, Preview } from "reallysimpledocs/components";
+
+# Button
+
+<Callout type="tip">MDX is optional. Plain Markdown stays the default.</Callout>
+```
+
 ## Use Basecoat on the rest of the site
 
 RSD styles and scripts its generated docs pages. For custom Astro pages outside the docs route, use Basecoat directly in your own layout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reallysimpledocs",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -20,6 +20,7 @@
     "check": "npm run build && npm pack --dry-run && npm run smoke:consumer"
   },
   "dependencies": {
+    "@astrojs/mdx": "^6.0.3",
     "@tailwindcss/vite": "4.1.17",
     "astro": "^6.4.6",
     "github-slugger": "^2.0.0",
@@ -29,11 +30,11 @@
     "shiki": "^4.1.0"
   },
   "peerDependencies": {
-    "basecoat-css": "^1.0.0-beta.1",
+    "basecoat-css": "^1.0.0-beta.2",
     "tailwindcss": ">=4.1.17 <5"
   },
   "devDependencies": {
-    "basecoat-css": "^1.0.0-beta.1",
+    "basecoat-css": "1.0.0-beta.2",
     "tailwindcss": "4.1.17"
   },
   "overrides": {

package/src/astro/index.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
+import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 
 const basecoatStyles = new Set(["vega", "nova", "maia", "lyra", "mira", "luma", "sera", "rhea"]);
@@ -23,6 +24,28 @@ const cssPath = (relativePath) => fileURLToPath(new URL(`../css/${relativePath}`
 
 const normalizeArray = (value) => (Array.isArray(value) ? value : value ? [value] : []);
 
+const normalizeImportPath = (filePath) => filePath.replaceAll(path.sep, "/");
+
+function collectMdxModules(docsDir) {
+  if (!fs.existsSync(docsDir)) return {};
+  const modules = {};
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".mdx")) continue;
+      const relative = path.relative(docsDir, fullPath).replaceAll(path.sep, "/");
+      const slug = relative.replace(/\.mdx$/, "");
+      modules[slug] = normalizeImportPath(fullPath);
+    }
+  };
+  walk(docsDir);
+  return modules;
+}
+
 export default function reallySimpleDocs(options = {}) {
   const style = options.style || "vega";
   if (!basecoatStyles.has(style)) {
@@ -47,13 +70,15 @@ export default function reallySimpleDocs(options = {}) {
         const root = fileURLToPath(config.root);
         const generatedDir = path.join(root, ".astro", "reallysimpledocs");
         const generatedStyles = path.join(generatedDir, "styles.css");
+        const docsDir = path.resolve(root, normalizedOptions.docsDir);
         const virtualConfig = {
           ...normalizedOptions,
           root,
-          docsDir: path.resolve(root, normalizedOptions.docsDir),
+          docsDir,
           siteFile: normalizedOptions.siteFile ? path.resolve(root, normalizedOptions.siteFile) : null,
           routeBase: normalizeRouteBase(normalizedOptions.routeBase),
         };
+        const mdxModules = collectMdxModules(docsDir);
         const resolveUserId = (id) => (id?.startsWith(".") ? path.resolve(root, id) : id);
         const components = {
           SidebarHeader:
@@ -71,7 +96,7 @@ export default function reallySimpleDocs(options = {}) {
             `@import ${JSON.stringify(cssPath("overrides.css"))};`,
             ...normalizedOptions.customCss.map((css) => `@import ${JSON.stringify(resolveUserId(css))};`),
             `@source ${JSON.stringify(runtimePath("**/*.{astro,js,ts}"))};`,
-            `@source ${JSON.stringify(path.join(virtualConfig.docsDir, "**/*.md"))};`,
+            `@source ${JSON.stringify(path.join(virtualConfig.docsDir, "**/*.{md,mdx}"))};`,
             "",
           ].join("\n"),
         );
@@ -98,6 +123,7 @@ export default function reallySimpleDocs(options = {}) {
         });
 
         updateConfig({
+          integrations: [mdx()],
           vite: {
             build: {
               cssMinify: false,
@@ -108,6 +134,7 @@ export default function reallySimpleDocs(options = {}) {
                 name: "reallysimpledocs-virtual-modules",
                 resolveId(id) {
                   if (id === "virtual:reallysimpledocs/config") return "\0virtual:reallysimpledocs/config";
+                  if (id === "virtual:reallysimpledocs/mdx-pages") return "\0virtual:reallysimpledocs/mdx-pages";
                   if (id === "virtual:reallysimpledocs/styles.css") return generatedStyles;
                   if (id === "virtual:reallysimpledocs/components/SidebarHeader") {
                     return "\0virtual:reallysimpledocs/components/SidebarHeader";
@@ -116,6 +143,22 @@ export default function reallySimpleDocs(options = {}) {
                 },
                 load(id) {
                   if (id === "\0virtual:reallysimpledocs/config") return `export default ${JSON.stringify(virtualConfig)};`;
+                  if (id === "\0virtual:reallysimpledocs/mdx-pages") {
+                    const imports = Object.entries(mdxModules)
+                      .map(([slug, filePath], index) => `import * as mdx${index} from ${JSON.stringify(filePath)};`)
+                      .join("\n");
+                    const moduleMap = Object.fromEntries(Object.keys(mdxModules).map((slug, index) => [slug, `mdx${index}`]));
+                    return `${imports}
+const modules = {
+${Object.entries(moduleMap)
+  .map(([slug, name]) => `  ${JSON.stringify(slug)}: ${name},`)
+  .join("\n")}
+};
+export async function getMdxPage(slug) {
+  return modules[slug || "index"] || null;
+}
+`;
+                  }
                   if (id === "\0virtual:reallysimpledocs/components/SidebarHeader") {
                     return `export { default } from ${JSON.stringify(resolveUserId(components.SidebarHeader))};`;
                   }

package/src/components/index.js

@@ -2,3 +2,14 @@ export { default as DocsLayout } from "../runtime/components/DocsLayout.astro";
 export { default as CommandDialog } from "../runtime/components/CommandDialog.astro";
 export { default as DropdownMenu } from "../runtime/components/DropdownMenu.astro";
 export { default as Sidebar } from "../runtime/components/Sidebar.astro";
+export { default as Badge } from "../runtime/components/mdx/Badge.astro";
+export { default as Callout } from "../runtime/components/mdx/Callout.astro";
+export { default as Card } from "../runtime/components/mdx/Card.astro";
+export { default as CardGrid } from "../runtime/components/mdx/CardGrid.astro";
+export { default as Code } from "../runtime/components/mdx/Code.astro";
+export { default as CodeGroup } from "../runtime/components/mdx/CodeGroup.astro";
+export { default as LinkButton } from "../runtime/components/mdx/LinkButton.astro";
+export { default as Preview } from "../runtime/components/mdx/Preview.astro";
+export { default as Step } from "../runtime/components/mdx/Step.astro";
+export { default as Steps } from "../runtime/components/mdx/Steps.astro";
+export { default as Tabs } from "../runtime/components/mdx/Tabs.astro";

package/src/css/custom.css

@@ -20,6 +20,9 @@
   > h3 {
     @apply text-lg sm:text-xl lg:mt-8;
   }
+  > h1:first-child {
+    @apply hidden;
+  }
   p > a,
   li > a,
   dt > a,
@@ -38,10 +41,7 @@
     @apply block min-w-full w-max px-4 py-3 text-[13px];
   }
   pre:has(> code) {
-    @apply relative max-w-full overflow-x-auto;
-  }
-  pre:has(> code) > button {
-    @apply flex items-center justify-center size-6 absolute right-2.5 top-2.5 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] rounded-md hover:bg-accent dark:hover:bg-accent/50 text-muted-foreground hover:text-foreground [&_svg]:size-4;
+    @apply max-w-full overflow-x-auto;
   }
   blockquote {
     @apply border-l-4 border-border pl-4;
@@ -140,18 +140,194 @@ html.dark .shiki span {
   @apply sm:max-w-2xl;
 }
 
-.command [data-rsd-search-result] {
+[data-search] .command a[role='menuitem'] {
   @apply flex-col items-start gap-1;
 }
 
-.command [data-rsd-search-title] {
+[data-search] .command a[role='menuitem'] > strong {
   @apply font-medium;
 }
 
-.command [data-rsd-search-snippet] {
+[data-search] .command a[role='menuitem'] > span {
   @apply text-muted-foreground line-clamp-2 text-xs font-normal leading-snug;
 }
 
 .command mark {
   @apply bg-search-highlight/50 text-foreground rounded-sm px-0.5 dark:bg-search-highlight/25;
 }
+
+.docs-card-link {
+  @apply transition-colors hover:bg-muted/50 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50;
+}
+
+.alert[data-variant='warning'] > svg,
+.alert[data-variant='warning'] > h3,
+.alert[data-variant='warning'] > section {
+  @apply text-amber-700 dark:text-amber-300;
+}
+
+.alert-destructive[data-variant='danger'] > svg,
+.alert-destructive[data-variant='danger'] > h3,
+.alert-destructive[data-variant='danger'] > section {
+  @apply text-destructive;
+}
+
+.code-block {
+  @apply relative my-6 max-w-full overflow-hidden rounded-lg;
+}
+
+.code-block > header,
+.code-group > header,
+.preview > header {
+  @apply flex h-10 items-center gap-2 border-b border-border/50 bg-muted px-3 text-sm font-medium dark:bg-muted/50;
+}
+
+.code-block > header > :first-child,
+.code-group > header > :first-child,
+.preview > header > :first-child {
+  @apply mr-auto;
+}
+
+.code-block > pre {
+  @apply my-0 max-w-full overflow-x-auto rounded-none border-0;
+}
+
+.code-block > pre > code {
+  @apply block min-w-full w-max px-4 py-3 text-[13px];
+}
+
+.code-block > .shiki {
+  @apply my-0 rounded-none border-0;
+}
+
+.code-block > button {
+  @apply absolute right-2.5 top-2.5;
+}
+
+.code-block button,
+.code-group button[aria-label='Copy code'],
+.preview button[aria-label='Copy code'] {
+  @apply flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:hover:bg-accent/50 [&_svg]:size-4;
+}
+
+.code-block > header > button,
+.code-group > header > button,
+.preview > header > button {
+  @apply ml-auto;
+}
+
+.code-group {
+  @apply relative my-6 max-w-full overflow-hidden rounded-lg;
+}
+
+.code-group > header > .tabs {
+  @apply my-0 min-w-0 max-w-full gap-0;
+}
+
+.code-group > header > .tabs > nav {
+  @apply h-full justify-start rounded-none bg-transparent p-0;
+}
+
+.code-group > [role='tabpanel'] {
+  @apply border-t-0;
+}
+
+.code-group .code-block {
+  @apply my-0 min-w-0 rounded-none;
+}
+
+.code-group .code-block > header {
+  @apply hidden;
+}
+
+.preview {
+  @apply relative my-6 max-w-full overflow-hidden rounded-lg border border-border/50 bg-muted dark:bg-muted/50;
+}
+
+.preview > header > .tabs {
+  @apply my-0 min-w-0 max-w-full gap-0;
+}
+
+.preview > header > .tabs > nav {
+  @apply h-full justify-start rounded-none bg-transparent p-0;
+}
+
+.preview > [role='tabpanel'] {
+  @apply border-t-0;
+}
+
+.preview > [data-code-panel] .code-block {
+  @apply my-0 min-w-0 rounded-none;
+}
+
+.preview > header > button[aria-label='Copy code'] {
+  display: none;
+}
+
+.preview:has(> [data-code-panel]:not([hidden])) > header > button[aria-label='Copy code'] {
+  display: flex;
+}
+
+.preview > [data-preview-panel] > div {
+  @apply flex min-h-64 w-full items-center justify-center bg-muted p-6 dark:bg-muted/50;
+}
+
+.steps {
+  @apply mb-12 mt-6 md:ml-4 md:border-l md:pl-8;
+  counter-reset: step;
+}
+
+.steps > section {
+  counter-increment: step;
+}
+
+.steps > section > h3 {
+  @apply relative mt-12 scroll-m-28 text-lg font-medium tracking-tight;
+}
+
+.steps > section:first-child > h3 {
+  @apply mt-0;
+}
+
+.steps > section > h3::before {
+  @apply mr-4 inline-flex size-7 items-center justify-center rounded-full bg-muted text-sm font-medium text-muted-foreground;
+  content: counter(step);
+}
+
+@media (width >= 48rem) {
+  .steps > section > h3::before {
+    position: absolute;
+    left: 0;
+    top: 0;
+    margin-right: 0;
+    transform: translateX(-2.875rem);
+  }
+}
+
+.steps > section > * + * {
+  @apply mt-6;
+}
+
+.steps > section > h3 + * {
+  @apply mt-4;
+}
+
+.steps > section > * {
+  @apply leading-relaxed;
+}
+
+.steps > section > *:first-child {
+  @apply mt-0;
+}
+
+.steps > section > *:last-child {
+  @apply mb-0;
+}
+
+.prose > .alert,
+.prose > .alert-destructive,
+.prose > .card,
+.prose > .grid,
+.prose > .tabs {
+  @apply my-6;
+}

package/src/runtime/components/CommandDialog.astro

@@ -4,7 +4,7 @@ import { renderCommandDialog } from "../lib/macros.js";
 const { indexUrl } = Astro.props;
 ---
 
-<div data-rsd-command-search data-index-url={indexUrl}>
+<div data-search data-index-url={indexUrl}>
   <Fragment
     set:html={renderCommandDialog({
       id: "command-search",
@@ -18,7 +18,7 @@ const { indexUrl } = Astro.props;
 <script>
   import lunr from "lunr";
 
-  const root = document.querySelector("[data-rsd-command-search]");
+  const root = document.querySelector("[data-search]");
   const indexUrl = root?.getAttribute("data-index-url");
   const dialog = document.getElementById("command-search");
   const command = dialog?.querySelector(".command");
@@ -178,9 +178,9 @@ const { indexUrl } = Astro.props;
       ${items
         .map((item, index) => {
           const view = resultView(item, query);
-          return `<a id="command-search-result-${index}" role="menuitem" data-force data-rsd-search-result href="${escapeHtml(view.path)}">
-            <span data-rsd-search-title>${view.title}</span>
-            ${view.snippet ? `<span data-rsd-search-snippet>${view.snippet}</span>` : ""}
+          return `<a id="command-search-result-${index}" role="menuitem" data-force href="${escapeHtml(view.path)}">
+            <strong>${view.title}</strong>
+            ${view.snippet ? `<span>${view.snippet}</span>` : ""}
           </a>`;
         })
       .join("")}

package/src/runtime/components/mdx/Badge.astro

@@ -0,0 +1,15 @@
+---
+const { variant = "secondary", class: className = "" } = Astro.props;
+const variants = {
+  primary: "badge-primary",
+  secondary: "badge-secondary",
+  destructive: "badge-destructive",
+  outline: "badge-outline",
+  ghost: "badge-ghost",
+  link: "badge-link",
+};
+---
+
+<span class:list={[variants[variant] || "badge-secondary", className]}>
+  <slot />
+</span>

package/src/runtime/components/mdx/Callout.astro

@@ -0,0 +1,54 @@
+---
+import CircleAlert from "lucide-static/icons/circle-alert.svg?raw";
+import Info from "lucide-static/icons/info.svg?raw";
+import Lightbulb from "lucide-static/icons/lightbulb.svg?raw";
+import TriangleAlert from "lucide-static/icons/triangle-alert.svg?raw";
+import * as lucideIcons from "lucide-static";
+import { addSvgClass } from "../../lib/html.js";
+
+const { type, variant, title, icon: showIcon = true, class: className = "" } = Astro.props;
+const normalizedType = String(variant || type || "note").toLowerCase();
+const calloutType = normalizedType === "note" ? "info" : normalizedType;
+const destructive = calloutType === "danger";
+const labels = {
+  note: "Note",
+  info: "Info",
+  tip: "Tip",
+  warning: "Warning",
+  danger: "Danger",
+};
+const icons = {
+  note: Info,
+  info: Info,
+  tip: Lightbulb,
+  warning: TriangleAlert,
+  danger: CircleAlert,
+};
+
+function resolveNamedIcon(name) {
+  if (!name || typeof name !== "string") return "";
+  const trimmed = name.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("<svg")) return trimmed;
+  const pascalName = trimmed.includes("-")
+    ? trimmed
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("")
+    : trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+  return lucideIcons[pascalName] || "";
+}
+
+const iconSource =
+  showIcon === false ? "" : typeof showIcon === "string" ? resolveNamedIcon(showIcon) : icons[normalizedType] || Info;
+const icon = addSvgClass(iconSource, "size-4");
+const heading = title || labels[normalizedType] || labels.note;
+---
+
+<div class:list={[destructive ? "alert-destructive" : "alert", className]} data-variant={calloutType}>
+  {icon && <Fragment set:html={icon} />}
+  <h3>{heading}</h3>
+  <section>
+    <slot />
+  </section>
+</div>

package/src/runtime/components/mdx/Card.astro

@@ -0,0 +1,13 @@
+---
+const { title, description, href, class: className = "" } = Astro.props;
+const Tag = href ? "a" : "article";
+---
+
+<Tag href={href} class:list={["card w-full no-underline", href && "docs-card-link", className]}>
+  {(title || description) && (
+    <header>
+      {title && <h3>{title}</h3>}
+      {description && <p>{description}</p>}
+    </header>
+  )}
+</Tag>

package/src/runtime/components/mdx/CardGrid.astro

@@ -0,0 +1,7 @@
+---
+const { class: className = "" } = Astro.props;
+---
+
+<div class:list={["grid w-full gap-4 sm:grid-cols-2", className]}>
+  <slot />
+</div>

package/src/runtime/components/mdx/Code.astro

@@ -0,0 +1,19 @@
+---
+import { codeToHtml } from "shiki";
+
+const { code = "", lang = "text", title, class: className = "" } = Astro.props;
+const highlightLang = String(lang || "text").toLowerCase() === "mdx" ? "tsx" : String(lang || "text");
+const html = await codeToHtml(String(code || ""), {
+  lang: highlightLang,
+  themes: {
+    light: "github-light",
+    dark: "github-dark",
+  },
+  defaultColor: false,
+});
+---
+
+<div class:list={["code-block", className]}>
+  {title && <header><span>{title}</span></header>}
+  <Fragment set:html={html} />
+</div>

package/src/runtime/components/mdx/CodeGroup.astro

@@ -0,0 +1,56 @@
+---
+import Code from "./Code.astro";
+
+const { tabs = [], defaultTab, class: className = "" } = Astro.props;
+const id = `code-group-${Math.random().toString(36).slice(2)}`;
+const normalizedTabs = tabs.map((tab, index) => ({
+  ...tab,
+  value: tab.value || tab.label || String(index),
+  lang: tab.lang || "text",
+  code: tab.code || "",
+}));
+const defaultValue = defaultTab || normalizedTabs[0]?.value;
+---
+
+<div class:list={["code-group", className]}>
+  <header>
+    <div class="tabs">
+      <nav role="tablist" aria-orientation="horizontal" data-variant="line">
+        {
+          normalizedTabs.map((tab, index) => {
+            const selected = tab.value === defaultValue;
+            return (
+              <button
+                type="button"
+                role="tab"
+                id={`${id}-tab-${index + 1}`}
+                aria-controls={`${id}-panel-${index + 1}`}
+                aria-selected={selected ? "true" : "false"}
+                tabindex={selected ? "0" : "-1"}
+              >
+                {tab.label}
+              </button>
+            );
+          })
+        }
+      </nav>
+    </div>
+  </header>
+  {
+    normalizedTabs.map((tab, index) => {
+      const selected = tab.value === defaultValue;
+      return (
+        <div
+          role="tabpanel"
+          id={`${id}-panel-${index + 1}`}
+          aria-labelledby={`${id}-tab-${index + 1}`}
+          tabindex="-1"
+          aria-selected={selected ? "true" : "false"}
+          hidden={!selected}
+        >
+          <Code code={tab.code} lang={tab.lang} />
+        </div>
+      );
+    })
+  }
+</div>

package/src/runtime/components/mdx/LinkButton.astro

@@ -0,0 +1,14 @@
+---
+const { href, variant = "default", class: className = "", target, rel } = Astro.props;
+const variants = {
+  default: "btn",
+  secondary: "btn-secondary",
+  outline: "btn-outline",
+  ghost: "btn-ghost",
+  link: "btn-link",
+};
+---
+
+<a href={href} target={target} rel={rel} class:list={[variants[variant] || "btn", className]}>
+  <slot />
+</a>

package/src/runtime/components/mdx/Preview.astro

@@ -0,0 +1,58 @@
+---
+import Code from "./Code.astro";
+
+const { code = "", lang = "html", title = "Preview", class: className = "" } = Astro.props;
+const id = `preview-${Math.random().toString(36).slice(2)}`;
+---
+
+<section class="preview">
+  <header>
+    <div class="tabs">
+      <nav role="tablist" aria-orientation="horizontal" data-variant="line">
+        <button
+          type="button"
+          role="tab"
+          id={`${id}-preview-tab`}
+          aria-controls={`${id}-preview-panel`}
+          aria-selected="true"
+          tabindex="0"
+        >
+          {title}
+        </button>
+        <button
+          type="button"
+          role="tab"
+          id={`${id}-code-tab`}
+          aria-controls={`${id}-code-panel`}
+          aria-selected="false"
+          tabindex="-1"
+        >
+          Code
+        </button>
+      </nav>
+    </div>
+  </header>
+  <section
+    role="tabpanel"
+    data-preview-panel
+    id={`${id}-preview-panel`}
+    aria-labelledby={`${id}-preview-tab`}
+    tabindex="-1"
+    aria-selected="true"
+  >
+    <div class={className}>
+      <slot />
+    </div>
+  </section>
+  <section
+    role="tabpanel"
+    data-code-panel
+    id={`${id}-code-panel`}
+    aria-labelledby={`${id}-code-tab`}
+    tabindex="-1"
+    aria-selected="false"
+    hidden
+  >
+    <Code code={code} lang={lang} />
+  </section>
+</section>

package/src/runtime/components/mdx/Step.astro

@@ -0,0 +1,8 @@
+---
+const { title, class: className = "" } = Astro.props;
+---
+
+<section role="listitem" class={className}>
+  {title && <h3>{title}</h3>}
+  <slot />
+</section>

package/src/runtime/components/mdx/Steps.astro

@@ -0,0 +1,7 @@
+---
+const { class: className = "" } = Astro.props;
+---
+
+<div role="list" class:list={["steps", className]}>
+  <slot />
+</div>

package/src/runtime/components/mdx/Tabs.astro

@@ -0,0 +1,52 @@
+---
+const { tabs = [], defaultTab, orientation = "horizontal", variant, class: className = "" } = Astro.props;
+const id = `tabs-${Math.random().toString(36).slice(2)}`;
+const normalizedTabs = tabs.map((tab, index) => ({
+  ...tab,
+  slot: tab.slot || String(index),
+  value: tab.value || tab.slot || String(index),
+}));
+const defaultValue = defaultTab || normalizedTabs.find((tab) => !tab.disabled)?.value || normalizedTabs[0]?.value;
+---
+
+<div class:list={["tabs", className]}>
+  <nav role="tablist" aria-orientation={orientation} data-variant={variant}>
+    {
+      normalizedTabs.map((tab, index) => {
+        const selected = tab.value === defaultValue;
+        return (
+          <button
+            type="button"
+            role="tab"
+            id={`${id}-tab-${index + 1}`}
+            aria-controls={`${id}-panel-${index + 1}`}
+            aria-selected={selected ? "true" : "false"}
+            tabindex={selected && !tab.disabled ? "0" : "-1"}
+            disabled={tab.disabled}
+          >
+            {tab.label}
+          </button>
+        );
+      })
+    }
+  </nav>
+  {
+    await Promise.all(
+      normalizedTabs.map(async (tab, index) => {
+        const selected = tab.value === defaultValue;
+        return (
+          <div
+            role="tabpanel"
+            id={`${id}-panel-${index + 1}`}
+            aria-labelledby={`${id}-tab-${index + 1}`}
+            tabindex="-1"
+            aria-selected={selected ? "true" : "false"}
+            hidden={!selected}
+          >
+            <Fragment set:html={await Astro.slots.render(tab.slot)} />
+          </div>
+        );
+      }),
+    )
+  }
+</div>

package/src/runtime/lib/docs.js

@@ -19,7 +19,16 @@ export const fallbackLabelFromSlug = (slug) => {
   return base.replace(/-/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
 };
 
-export const slugToFile = (slug) => path.join(...String(slug).split("/")) + ".md";
+export const slugToFile = (slug, extension = ".md") => path.join(...String(slug).split("/")) + extension;
+
+export function resolveDocFile(config, slug) {
+  for (const extension of [".md", ".mdx"]) {
+    const file = slugToFile(slug, extension);
+    const filePath = path.join(config.docsDir, file);
+    if (fs.existsSync(filePath)) return { file, filePath, extension };
+  }
+  throw new Error(`Missing docs page for slug "${slug}". Expected .md or .mdx in ${config.docsDir}.`);
+}
 
 export function flattenMenuSlugs(menu) {
   const out = [];
@@ -44,13 +53,13 @@ export function flattenMenuSlugs(menu) {
 export function getPages(config) {
   const manifest = getManifest(config);
   return flattenMenuSlugs(manifest.menu || []).map((slug) => {
-    const file = slugToFile(slug);
-    const filePath = path.join(config.docsDir, file);
+    const { file, filePath, extension } = resolveDocFile(config, slug);
     const source = fs.readFileSync(filePath, "utf8");
     const parsed = parseDocMarkdown(source, fallbackLabelFromSlug(slug));
     return {
       slug,
       file,
+      extension,
       path: routePath(config.routeBase, slug),
       markdownPath: markdownPath(config.routeBase, slug),
       title: parsed.title,
@@ -113,6 +122,20 @@ export async function renderDoc(config, page) {
   return { page, html, headings };
 }
 
+export function getDocHeadings(config, page) {
+  const parsed = parseDocMarkdown(getDocMarkdown(config, page), page.title);
+  const headings = [];
+  const slugger = new GithubSlugger();
+  const tokens = marked.lexer(parsed.body);
+  tokens.forEach((token) => {
+    if (token.type !== "heading" || token.depth <= 1 || token.depth >= 4) return;
+    const text = plainText(token.tokens || []).trim();
+    if (!text) return;
+    headings.push({ depth: token.depth, id: slugger.slug(text), text });
+  });
+  return headings;
+}
+
 export function renderNunjucksCompat(content) {
   return String(content).replace(
     /\{%\s*lucide\s+["']([^"']+)["'](?:\s*,\s*[^%]+)?\s*%\}/g,
@@ -156,7 +179,7 @@ export function buildMenus(config, currentSlug) {
       type: "item",
       icon,
       url: page.path,
-      label: page.title,
+      label: item.label || page.title,
       current: page.slug === currentSlug,
       keywords: page.title,
     };
@@ -231,7 +254,7 @@ export function getPageItemSlug(item) {
 }
 
 function parseDocMarkdown(source, fallbackTitle) {
-  const content = String(source || "").trimStart();
+  const content = normalizeDocSource(source);
   const tokens = marked.lexer(content);
   const first = tokens[0];
 
@@ -249,7 +272,18 @@ function parseDocMarkdown(source, fallbackTitle) {
 }
 
 function markdownPlainText(markdown) {
-  return tokensText(marked.lexer(renderNunjucksCompat(markdown)));
+  return tokensText(marked.lexer(renderNunjucksCompat(normalizeDocSource(markdown))));
+}
+
+function normalizeDocSource(source) {
+  const withoutFrontmatter = String(source || "")
+    .trimStart()
+    .replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+  const firstHeading = withoutFrontmatter.search(/^#\s+/m);
+  if (firstHeading > 0) return withoutFrontmatter.slice(firstHeading).trimStart();
+  return withoutFrontmatter
+    .replace(/^(\s*(?:import|export)\s+[^\n]*\n)+/m, "")
+    .trimStart();
 }
 
 async function highlightCode(tokens) {
@@ -296,6 +330,7 @@ async function highlightToken(token) {
 function normalizeLanguage(lang) {
   const value = lang?.trim().split(/\s+/)[0].toLowerCase() || "text";
   if (value === "njk") return "html";
+  if (value === "mdx") return "tsx";
   if (value === "sh" || value === "shell") return "bash";
   return value;
 }

package/src/runtime/lib/paths.js

@@ -2,12 +2,18 @@ export const stripSlashes = (value) => String(value || "").replace(/^\/+|\/+$/g,
 
 export const routePath = (routeBase, slug) => {
   const base = stripSlashes(routeBase);
-  const normalizedSlug = slug === "index" ? "" : stripSlashes(slug);
+  const strippedSlug = stripSlashes(slug);
+  const normalizedSlug =
+    strippedSlug === "index" ? "" : strippedSlug.endsWith("/index") ? strippedSlug.slice(0, -"/index".length) : strippedSlug;
   const parts = [base, normalizedSlug].filter(Boolean);
   return parts.length ? `/${parts.join("/")}/` : "/";
 };
 
-export const routeSlug = (slug) => (slug === "index" ? undefined : slug);
+export const routeSlug = (slug) => {
+  const strippedSlug = stripSlashes(slug);
+  if (strippedSlug === "index") return undefined;
+  return strippedSlug.endsWith("/index") ? strippedSlug.slice(0, -"/index".length) : strippedSlug;
+};
 
 export const markdownPath = (routeBase, slug) => {
   const base = stripSlashes(routeBase);

package/src/runtime/pages/doc.astro

@@ -1,7 +1,8 @@
 ---
 import config from "virtual:reallysimpledocs/config";
+import { getMdxPage } from "virtual:reallysimpledocs/mdx-pages";
 import DocsLayout from "../components/DocsLayout.astro";
-import { getPages, renderDoc } from "../lib/docs.js";
+import { getDocHeadings, getPages, renderDoc } from "../lib/docs.js";
 import { routeSlug } from "../lib/paths.js";
 
 export function getStaticPaths() {
@@ -12,9 +13,12 @@ export function getStaticPaths() {
 }
 
 const { page } = Astro.props;
-const doc = await renderDoc(config, page);
+const isMdx = page.extension === ".mdx";
+const mdxModule = isMdx ? await getMdxPage(page.slug) : null;
+const MdxContent = mdxModule?.Content || mdxModule?.default;
+const doc = isMdx ? { page, headings: getDocHeadings(config, page), html: "" } : await renderDoc(config, page);
 ---
 
 <DocsLayout page={page} headings={doc.headings}>
-  <Fragment set:html={doc.html} />
+  {MdxContent ? <MdxContent /> : <Fragment set:html={doc.html} />}
 </DocsLayout>

package/src/runtime/scripts/copy-code.js

@@ -19,18 +19,49 @@ const copyText = async (text) => {
   if (!ok) throw new Error("Copy failed");
 };
 
+const activePanelCode = (root) => root.querySelector(':scope > [role="tabpanel"]:not([hidden]) code');
+
 const initCopyCode = (codeBlock) => {
   const codeEl = codeBlock.querySelector(":scope > code");
   if (!codeEl) return;
 
+  let target = null;
+  let frame = codeBlock.closest(".code-group");
+  let getCode = frame ? () => activePanelCode(frame) || codeEl : () => codeEl;
+  if (frame) target = frame.querySelector(":scope > header");
+
+  const preview = codeBlock.closest(".preview");
+  const previewCodePanel = preview?.querySelector(":scope > [data-code-panel]");
+  if (!frame && previewCodePanel?.contains(codeBlock)) {
+    frame = preview;
+    target = frame.querySelector(":scope > header");
+    getCode = () => codeEl;
+  }
+
+  if (!frame) {
+    frame = codeBlock.parentElement?.classList.contains("code-block") ? codeBlock.parentElement : null;
+    if (!frame) {
+      frame = document.createElement("div");
+      frame.className = "code-block";
+      codeBlock.parentNode.insertBefore(frame, codeBlock);
+      frame.appendChild(codeBlock);
+    }
+  }
+
+  target ||= frame.querySelector(":scope > header") || frame;
+
+  if (target.querySelector(":scope > button[aria-label='Copy code']")) {
+    codeBlock.dataset.copyCodeInitialized = true;
+    return;
+  }
+
   const button = document.createElement("button");
   button.type = "button";
-  button.className = "code-block-copy";
   button.setAttribute("aria-label", "Copy code");
   button.innerHTML = Copy;
 
   button.addEventListener("click", async () => {
-    const text = (codeEl.textContent || "").replace(/\n$/, "");
+    const text = (getCode()?.textContent || "").replace(/\n$/, "");
     if (!text) return;
 
     button.disabled = true;
@@ -47,8 +78,8 @@ const initCopyCode = (codeBlock) => {
     }, 1200);
   });
 
-  codeBlock.insertBefore(button, codeBlock.firstChild);
+  target.appendChild(button);
   codeBlock.dataset.copyCodeInitialized = true;
 };
 
-window.basecoat?.register("copy-code", "pre:not([data-copy-code-initialized])", initCopyCode);
+window.basecoat?.register("copy-code", "pre:has(> code):not([data-copy-code-initialized])", initCopyCode);