reallysimpledocs 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -2,7 +2,7 @@
 
 A simple documentation system for Astro, built with **Basecoat** and **Tailwind CSS**.
 
-RSD keeps docs portable: content lives in `docs/`, navigation lives in `docs/docs.json`, and the Astro integration owns the docs UI.
+reallysimpledocs keeps docs portable: content lives in `docs/`, navigation lives in `docs/docs.json`, and the Astro integration owns the docs UI.
 
 ## Add to an Astro site
 
@@ -59,11 +59,19 @@ docs/
 Welcome to the docs.
 ```
 
-RSD injects docs pages, Lunr search, per-page Markdown exports, `llms.txt`, and `llms-full.txt`.
+reallysimpledocs injects docs pages, Lunr search, per-page Markdown exports, `llms.txt`, and `llms-full.txt`.
+
+Use `.mdx` when a page needs reallysimpledocs components. Common reallysimpledocs components are available by default, so you do not need to import them in each page:
+
+```mdx
+# Button
+
+<Callout title="MDX works">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.
+reallysimpledocs styles and scripts its generated docs pages. For custom Astro pages outside the docs route, use Basecoat directly in your own layout.
 
 Install stays the same:
 
@@ -93,7 +101,7 @@ import "basecoat-css/all.min";
 <slot />
 ```
 
-Use the same Basecoat `style` in your RSD config and your site stylesheet if you want the docs and custom pages to match.
+Use the same Basecoat `style` in your reallysimpledocs config and your site stylesheet if you want the docs and custom pages to match.
 
 ## Local development (this repo)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reallysimpledocs",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "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,41 @@ const cssPath = (relativePath) => fileURLToPath(new URL(`../css/${relativePath}`
 
 const normalizeArray = (value) => (Array.isArray(value) ? value : value ? [value] : []);
 
+const normalizeImportPath = (filePath) => filePath.replaceAll(path.sep, "/");
+
+const isInsideDir = (dir, file) => {
+  const relative = path.relative(dir, file);
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+
+const shikiConfig = {
+  themes: {
+    light: "github-light",
+    dark: "github-dark",
+  },
+  defaultColor: false,
+};
+
+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,10 +83,11 @@ 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),
         };
@@ -71,7 +108,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 +135,15 @@ export default function reallySimpleDocs(options = {}) {
         });
 
         updateConfig({
+          integrations: [
+            mdx({
+              syntaxHighlight: "shiki",
+              shikiConfig,
+            }),
+          ],
+          markdown: {
+            shikiConfig,
+          },
           vite: {
             build: {
               cssMinify: false,
@@ -106,8 +152,24 @@ export default function reallySimpleDocs(options = {}) {
               tailwindcss(),
               {
                 name: "reallysimpledocs-virtual-modules",
+                configureServer(server) {
+                  const invalidateMdxPages = () => {
+                    const module = server.moduleGraph.getModuleById("\0virtual:reallysimpledocs/mdx-pages");
+                    if (module) server.moduleGraph.invalidateModule(module);
+                    server.ws.send({ type: "full-reload" });
+                  };
+
+                  server.watcher.add(path.join(docsDir, "**/*.mdx"));
+                  server.watcher.on("add", (file) => {
+                    if (file.endsWith(".mdx") && isInsideDir(docsDir, file)) invalidateMdxPages();
+                  });
+                  server.watcher.on("unlink", (file) => {
+                    if (file.endsWith(".mdx") && isInsideDir(docsDir, file)) invalidateMdxPages();
+                  });
+                },
                 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 +178,23 @@ 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 mdxModules = collectMdxModules(docsDir);
+                    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,12 @@ 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 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 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;
@@ -119,20 +119,25 @@
   }
 }
 
-.shiki {
-  @apply bg-muted dark:bg-muted/50;
+.shiki,
+.astro-code {
+  @apply bg-muted/50;
+  background-color: color-mix(in oklab, var(--color-muted) 50%, transparent) !important;
   color: var(--shiki-light);
 }
 
-.shiki span {
+.shiki span,
+.astro-code span {
   color: var(--shiki-light);
 }
 
-html.dark .shiki {
+html.dark .shiki,
+html.dark .astro-code {
   color: var(--shiki-dark);
 }
 
-html.dark .shiki span {
+html.dark .shiki span,
+html.dark .astro-code span {
   color: var(--shiki-dark);
 }
 
@@ -140,15 +145,15 @@ 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;
 }
 

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("")}
@@ -199,7 +199,7 @@ const { indexUrl } = Astro.props;
 
   async function loadIndex() {
     if (state.index) return state;
-    if (!indexUrl) throw new Error("Missing RSD search index URL.");
+    if (!indexUrl) throw new Error("Missing reallysimpledocs search index URL.");
     if (!state.loadPromise) {
       renderLoading();
       state.loadPromise = fetch(indexUrl)

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

@@ -0,0 +1,41 @@
+---
+import * as lucideIcons from "lucide-static";
+import { addSvgClass } from "../../lib/html.js";
+
+const { type, title = "Note", icon: iconName, class: className = "" } = Astro.props;
+const normalizedType = String(type || "").toLowerCase();
+const calloutType = normalizedType === "warning" || normalizedType === "danger" ? normalizedType : "";
+const danger = calloutType === "danger";
+
+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 = typeof iconName === "string" ? resolveNamedIcon(iconName) : "";
+const icon = addSvgClass(iconSource, "size-4");
+const heading = title;
+const variantClass =
+  calloutType === "warning"
+    ? "[&>svg]:text-amber-700 [&>h3]:text-amber-700 [&>section]:text-amber-700 dark:[&>svg]:text-amber-300 dark:[&>h3]:text-amber-300 dark:[&>section]:text-amber-300"
+    : danger
+      ? "[&>svg]:text-destructive [&>h3]:text-destructive [&>section]:text-destructive"
+      : "";
+---
+
+<div class:list={[danger ? "alert-destructive" : "alert", "my-6", variantClass, className]}>
+  {icon && <Fragment set:html={icon} />}
+  <h3>{heading}</h3>
+  <section>
+    <slot />
+  </section>
+</div>

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

@@ -0,0 +1,14 @@
+---
+const { title, description, href, class: className = "" } = Astro.props;
+const Tag = href ? "a" : "article";
+const classes = [
+  "my-6 block w-full rounded-lg border bg-card p-3 text-card-foreground no-underline",
+  href && "transition-colors hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50",
+  className,
+];
+---
+
+<Tag href={href} class:list={classes}>
+  {title && <h3 class="font-medium">{title}</h3>}
+  {description && <p class="mt-1 text-sm text-muted-foreground">{description}</p>}
+</Tag>

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

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

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

@@ -0,0 +1,39 @@
+---
+import { highlightCode } from "../../lib/highlight.js";
+
+const { lang = "text", title, class: className = "" } = Astro.props;
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const rawCode = decodeSlotText(slotHtml);
+const html = await highlightCode(rawCode, lang);
+const classes = [
+  "relative my-6 w-full max-w-full overflow-hidden rounded-lg",
+  className,
+];
+
+function decodeSlotText(value) {
+  return String(value || "")
+    .replace(/^<p>/, "")
+    .replace(/<\/p>$/, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .trim();
+}
+---
+
+<div
+  data-code-block
+  data-code-title={title || undefined}
+  class:list={classes}
+>
+  {
+    title && (
+      <header class="flex h-10 items-center gap-2 border-b border-border/50 bg-muted/50 px-3 text-sm font-medium">
+        <span class="mr-auto">{title}</span>
+      </header>
+    )
+  }
+  <Fragment set:html={html} />
+</div>

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

@@ -0,0 +1,80 @@
+---
+const { defaultTab, class: className = "" } = Astro.props;
+const id = `code-group-${Math.random().toString(36).slice(2)}`;
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const normalizedTabs = parseCodeTabs(slotHtml);
+const defaultValue = defaultTab || normalizedTabs[0]?.value;
+const classes = [
+  "relative my-6 w-full max-w-full overflow-hidden rounded-lg [&>[role=tabpanel]]:border-t-0 [&_[data-code-block]]:my-0 [&_[data-code-block]]:min-w-0 [&_[data-code-block]]:rounded-none [&_[data-code-block]>header]:hidden",
+  className,
+];
+
+function parseCodeTabs(html) {
+  const blocks = [];
+  const pattern =
+    /<div\b(?=[^>]*\bdata-code-block\b)(?=[^>]*\bdata-code-title="([^"]*)")[^>]*>([\s\S]*?)<\/div>/g;
+  let match;
+  while ((match = pattern.exec(html))) {
+    const label = decodeHtml(match[1]).trim();
+    if (!label) continue;
+    blocks.push({
+      label,
+      value: label,
+      html: match[0],
+    });
+  }
+  return blocks;
+}
+
+function decodeHtml(value) {
+  return String(value || "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+}
+---
+
+<div class:list={classes} data-code-group>
+  <header class="flex h-10 items-center gap-2 border-b border-border/50 bg-muted/50 px-3 text-sm font-medium">
+    <div class="tabs my-0 min-w-0 max-w-full gap-0">
+      <nav class="h-full justify-start rounded-none bg-transparent p-0" 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}
+        >
+          <Fragment set:html={tab.html} />
+        </div>
+      );
+    })
+  }
+</div>

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

@@ -0,0 +1,67 @@
+---
+import { highlightCode } from "../../lib/highlight.js";
+
+const { code = "", lang = "html", title = "Preview", class: className = "" } = Astro.props;
+const id = `preview-${Math.random().toString(36).slice(2)}`;
+const html = await highlightCode(code, lang);
+---
+
+<section
+  class="relative my-6 max-w-full overflow-hidden rounded-lg border [&>[role=tabpanel]]:border-t-0 [&>[data-code-panel]_[data-code-block]]:my-0 [&>[data-code-panel]_[data-code-block]]:min-w-0 [&>[data-code-panel]_[data-code-block]]:rounded-none [&>[data-preview-panel]>div]:flex [&>[data-preview-panel]>div]:min-h-64 [&>[data-preview-panel]>div]:w-full [&>[data-preview-panel]>div]:items-center [&>[data-preview-panel]>div]:justify-center [&>[data-preview-panel]>div]:p-6"
+  data-preview
+>
+  <header class="flex h-10 items-center gap-2 border-b border-border/50 bg-muted/50 px-3 text-sm font-medium">
+    <div class="tabs my-0 min-w-0 max-w-full gap-0">
+      <nav class="h-full justify-start rounded-none bg-transparent p-0" 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
+  >
+    <div
+      class="relative my-6 w-full max-w-full overflow-hidden rounded-lg"
+      data-code-block
+    >
+      <Fragment set:html={html} />
+    </div>
+  </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,11 @@
+---
+const { class: className = "" } = Astro.props;
+const classes = [
+  "mb-12 mt-6 [counter-reset:step] md:ml-4 md:border-l md:pl-8 [&>section]:mb-10 [&>section]:[counter-increment:step] [&>section:last-child]:mb-0 [&>section>*+*]:mt-6 [&>section>*]:leading-relaxed [&>section>*:first-child]:mt-0 [&>section>*:last-child]:mb-0 [&>section>h3+*]:mt-4 [&>section>h3]:relative [&>section>h3]:scroll-m-28 [&>section>h3]:text-lg [&>section>h3]:font-medium [&>section>h3]:tracking-tight [&>section>h3]:before:mr-4 [&>section>h3]:before:inline-flex [&>section>h3]:before:size-7 [&>section>h3]:before:items-center [&>section>h3]:before:justify-center [&>section>h3]:before:rounded-full [&>section>h3]:before:bg-muted [&>section>h3]:before:text-sm [&>section>h3]:before:font-medium [&>section>h3]:before:text-muted-foreground [&>section>h3]:before:content-[counter(step)] md:[&>section>h3]:before:absolute md:[&>section>h3]:before:left-0 md:[&>section>h3]:before:top-0 md:[&>section>h3]:before:mr-0 md:[&>section>h3]:before:-translate-x-[2.875rem]",
+  className,
+];
+---
+
+<div role="list" class:list={classes}>
+  <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 my-6", 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

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { marked } from "marked";
 import GithubSlugger from "github-slugger";
-import { codeToHtml } from "shiki";
 import * as lucideIcons from "lucide-static";
+import { highlightCode as renderHighlightedCode } from "./highlight.js";
 import { markdownPath, routePath } from "./paths.js";
 
 export function getManifest(config) {
@@ -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,
@@ -108,11 +117,25 @@ export async function renderDoc(config, page) {
   };
 
   const tokens = marked.lexer(content);
-  await highlightCode(tokens);
+  await highlightMarkdownCode(tokens);
   const html = marked.parser(tokens, { renderer });
   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,
@@ -141,7 +164,9 @@ export function resolveIcon(icon) {
         .join("")
     : trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
   const iconClass = trimmed.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-  return lucideIcons[pascalName]?.replace('class="lucide', `class="lucide lucide-${iconClass}`) || "";
+  const svg = lucideIcons[pascalName] || "";
+  if (!svg || svg.includes(`lucide-${iconClass}`)) return svg;
+  return svg.replace('class="lucide', `class="lucide lucide-${iconClass}`);
 }
 
 export function buildMenus(config, currentSlug) {
@@ -156,7 +181,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 +256,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,10 +274,21 @@ 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(/^(?:[ \t]*(?:import|export)\s+[^\n]*\n)+/, "")
+    .trimStart();
 }
 
-async function highlightCode(tokens) {
+async function highlightMarkdownCode(tokens) {
   for (const token of tokens) {
     if (token.type === "code") {
       const html = await highlightToken(token);
@@ -266,36 +302,28 @@ async function highlightCode(tokens) {
     }
 
     for (const childTokens of nestedTokenLists(token)) {
-      await highlightCode(childTokens);
+      await highlightMarkdownCode(childTokens);
     }
   }
 }
 
 async function highlightToken(token) {
+  const lang = normalizeLanguage(token.lang);
   try {
-    return await codeToHtml(token.text, {
-      lang: normalizeLanguage(token.lang),
-      themes: {
-        light: "github-light",
-        dark: "github-dark",
-      },
-      defaultColor: false,
-    });
+    return wrapCodeBlock(await renderHighlightedCode(token.text, lang));
   } catch {
-    return codeToHtml(token.text, {
-      lang: "text",
-      themes: {
-        light: "github-light",
-        dark: "github-dark",
-      },
-      defaultColor: false,
-    });
+    return wrapCodeBlock(await renderHighlightedCode(token.text, "text"));
   }
 }
 
+function wrapCodeBlock(html) {
+  return `<div class="relative my-6 w-full max-w-full overflow-hidden rounded-lg" data-code-block>${html}</div>`;
+}
+
 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/highlight.js

@@ -0,0 +1,27 @@
+import { codeToHtml } from "shiki";
+
+export async function highlightCode(code, lang = "text") {
+  const value = String(code || "");
+  const language = String(lang || "text").toLowerCase() === "mdx" ? "tsx" : String(lang || "text");
+  const html = await codeToHtml(value, {
+    lang: language,
+    themes: {
+      light: "github-light",
+      dark: "github-dark",
+    },
+    defaultColor: false,
+  });
+  return addCodeLayoutClasses(html);
+}
+
+function addCodeLayoutClasses(html) {
+  return String(html)
+    .replace(
+      /<pre class="/,
+      '<pre class="!my-0 max-w-full overflow-x-auto !rounded-none !border-0 ',
+    )
+    .replace(
+      /<code>/,
+      '<code class="block min-w-full w-max px-4 py-3 text-[13px]">',
+    );
+}

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,9 @@
 ---
 import config from "virtual:reallysimpledocs/config";
+import { getMdxPage } from "virtual:reallysimpledocs/mdx-pages";
+import * as RsdComponents from "../../components/index.js";
 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 +14,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 components={RsdComponents} /> : <Fragment set:html={doc.html} />}
 </DocsLayout>

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

@@ -19,18 +19,63 @@ const copyText = async (text) => {
   if (!ok) throw new Error("Copy failed");
 };
 
+const activePanelCode = (root) => root.querySelector(':scope > [role="tabpanel"]:not([hidden]) code');
+const codeFrameClass = "relative my-6 w-full max-w-full overflow-hidden rounded-lg";
+const codePreClasses = ["!my-0", "max-w-full", "overflow-x-auto", "!rounded-none", "!border-0"];
+const codeContentClasses = ["block", "min-w-full", "w-max", "px-4", "py-3", "text-[13px]"];
+const copyButtonClass =
+  "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";
+
 const initCopyCode = (codeBlock) => {
   const codeEl = codeBlock.querySelector(":scope > code");
   if (!codeEl) return;
 
+  codeBlock.classList.add(...codePreClasses);
+  codeEl.classList.add(...codeContentClasses);
+
+  let target = null;
+  let frame = codeBlock.closest("[data-code-group]");
+  let getCode = frame ? () => activePanelCode(frame) || codeEl : () => codeEl;
+  if (frame) target = frame.querySelector(":scope > header");
+
+  const preview = codeBlock.closest("[data-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?.hasAttribute("data-code-block") ? codeBlock.parentElement : null;
+    if (!frame) {
+      frame = document.createElement("div");
+      frame.dataset.codeBlock = "";
+      frame.className = codeFrameClass;
+      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.className = `${copyButtonClass} ${
+    target === frame
+      ? "absolute right-2.5 top-2.5 bg-muted/50 shadow-sm backdrop-blur-sm"
+      : "ml-auto"
+  }`;
   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 +92,18 @@ const initCopyCode = (codeBlock) => {
     }, 1200);
   });
 
-  codeBlock.insertBefore(button, codeBlock.firstChild);
+  target.appendChild(button);
+  if (previewCodePanel?.contains(codeBlock)) {
+    const syncPreviewCopyButton = () => {
+      button.hidden = previewCodePanel.hidden;
+    };
+    syncPreviewCopyButton();
+    new MutationObserver(syncPreviewCopyButton).observe(previewCodePanel, {
+      attributes: true,
+      attributeFilter: ["hidden"],
+    });
+  }
   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);