reallysimpledocs 1.0.0-beta.5 → 1.0.0

package/README.md

@@ -1,18 +1,18 @@
 # ReallySimpleDocs
 
-A simple documentation system for Astro, built with **Basecoat** and **Tailwind CSS**.
+A simple documentation system for Astro, built with Basecoat and Tailwind CSS.
 
-ReallySimpleDocs 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, search, Markdown exports, and LLM files.
 
-## Add to an Astro site
+## Install
 
-ReallySimpleDocs is an Astro integration. Add it to an existing Astro site, or create one first with `npm create astro@latest`.
+Add ReallySimpleDocs to an Astro site:
 
 ```bash
-npm install reallysimpledocs basecoat-css tailwindcss
+npm install reallysimpledocs basecoat-css@beta tailwindcss
 ```
 
-Add the integration:
+Configure the integration:
 
 ```js
 // astro.config.mjs
@@ -25,17 +25,16 @@ export default defineConfig({
       docsDir: "./docs",
       routeBase: "/docs",
       style: "vega",
-      customCss: ["./src/docs.css"],
       site: {
-        title: "ReallySimpleDocs",
-        description: "A simple documentation system for Astro.",
+        title: "Acme Docs",
+        description: "Documentation for Acme.",
       },
     }),
   ],
 });
 ```
 
-Create docs:
+Create your first docs page:
 
 ```text
 docs/
@@ -61,9 +60,19 @@ docs/
 Welcome to the docs.
 ```
 
-ReallySimpleDocs injects docs pages, Lunr search, per-page Markdown exports, `llms.txt`, and `llms-full.txt`.
+## What it provides
 
-Use component overrides for layout chrome such as sidebar branding, extra head tags, or header controls between search and the built-in theme toggle:
+- Static docs routes from Markdown and MDX files.
+- Sidebar navigation from `docs/docs.json`.
+- Lunr search with a built-in command dialog.
+- Syntax-highlighted code blocks with copy buttons.
+- `llms.txt`, `llms-full.txt`, and per-page Markdown exports.
+- Basecoat styling with style-specific RSD CSS for docs surfaces.
+- Component slots for additive head content, sidebar chrome, and header controls.
+
+## Customization
+
+Use `components.ContentHeader` for controls between search and the built-in theme toggle:
 
 ```js
 reallySimpleDocs({
@@ -73,38 +82,48 @@ reallySimpleDocs({
 });
 ```
 
-For example, put only the GitHub button in `ContentHeader`; the theme toggle stays built in.
+Use `components.Head` to add tags to `<head>`. RSD's built-in metadata, theme setup, Basecoat JavaScript, copy-code behavior, and search behavior still render.
 
-Use `.mdx` when a page needs ReallySimpleDocs components. Common components are available by default, so you do not need to import them in each page:
+Use `customCss` for project CSS imported after Basecoat and RSD styles:
+
+```js
+reallySimpleDocs({
+  style: "nova",
+  customCss: ["./src/docs.css"],
+});
+```
 
-```mdx
-# Button
+Use `css: false` only when you provide the full Tailwind/Basecoat/RSD stylesheet pipeline yourself. RSD exports its own CSS for that case:
 
-<Callout title="MDX works">MDX is optional. Plain Markdown stays the default.</Callout>
+```css
+@import "reallysimpledocs/css";
+@import "reallysimpledocs/css/styles/vega";
 ```
 
-## Use Basecoat outside the docs
+## Search outside docs
 
-By default, ReallySimpleDocs manages one Tailwind/Basecoat stylesheet for the app. It scans `src/`, `docs/`, and the ReallySimpleDocs runtime, so Basecoat and Tailwind classes used by custom Astro pages outside the docs route are included in the same CSS build.
+Render the exported `CommandDialog` on any Astro page where you want docs search:
 
-Disable managed CSS only when you want to provide the full stylesheet pipeline yourself:
+```astro
+---
+import { CommandDialog } from "reallysimpledocs/components";
+---
 
-```js
-reallySimpleDocs({
-  css: false,
-});
-```
+<CommandDialog />
 
-Use `css: false` when you bring your own Tailwind/Basecoat/RSD stylesheet. ReallySimpleDocs still provides its managed JavaScript.
+<button type="button" class="btn" onclick="window.rsdOpenCommandSearch?.()">
+  Search docs
+</button>
+```
 
-## Local development (this repo)
+## Local development
 
 ```bash
 npm install
 npm run dev
 ```
 
-Useful checks before publishing changes:
+Useful checks before publishing:
 
 ```bash
 npm run build
@@ -112,17 +131,18 @@ npm pack --dry-run
 npm run smoke:consumer
 ```
 
+`npm run check` runs all three.
+
 ## Documentation
 
-Go to [ReallySimpleDocs.com](https://reallysimpledocs.com).
+Go to [reallysimpledocs.com](https://reallysimpledocs.com).
 
-## Support the project 
+## Support
 
-- [Contribute code](/CONTRIBUTING.md)
 - [Report issues](https://github.com/hunvreus/reallysimpledocs/issues)
 - [Sponsor me](https://github.com/sponsors/hunvreus)
 - [Star the project on GitHub](https://github.com/hunvreus/reallysimpledocs)
 
 ## License
 
-[MIT](/LICENSE.md)
+[MIT](LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reallysimpledocs",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -30,16 +30,19 @@
     "lucide-static": "^0.552.0",
     "lunr": "^2.3.9",
     "marked": "^16.4.1",
-    "shiki": "^4.1.0"
+    "rehype-parse": "^9.0.1",
+    "rehype-stringify": "^10.0.1",
+    "shiki": "^4.1.0",
+    "unified": "^11.0.5"
   },
   "peerDependencies": {
     "astro": "^6.4.6",
-    "basecoat-css": "^1.0.0-beta.5",
+    "basecoat-css": "^1.0.0-beta.6",
     "tailwindcss": ">=4.1.17 <5"
   },
   "devDependencies": {
     "astro": "^6.4.6",
-    "basecoat-css": "^1.0.0-beta.5",
+    "basecoat-css": "^1.0.0-beta.6",
     "tailwindcss": "4.1.17"
   },
   "overrides": {

package/src/astro/index.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import mdx from "@astrojs/mdx";
 import { unified } from "@astrojs/markdown-remark";
 import tailwindcss from "@tailwindcss/vite";
+import { rehypeBasecoatTables } from "./rehype-basecoat-tables.js";
 import { remarkPreviewSource } from "./preview-source.js";
+import { transformPreviewScripts } from "./preview-scripts.js";
 
 const basecoatStyles = new Set(["vega", "nova", "maia", "lyra", "mira", "luma", "sera", "rhea"]);
 
@@ -71,6 +73,7 @@ export default function reallySimpleDocs(options = {}) {
     style,
     customCss: normalizeArray(options.customCss),
     css: normalizeBoolean(options.css),
+    bodyAttrs: options.bodyAttrs || {},
     components: options.components || {},
     routeBase: options.routeBase ?? "/docs",
     assetsBase: options.assetsBase || "/assets",
@@ -156,6 +159,7 @@ export default function reallySimpleDocs(options = {}) {
           markdown: {
             processor: unified({
               remarkPlugins: [[remarkPreviewSource, { docsDir }]],
+              rehypePlugins: [rehypeBasecoatTables],
             }),
             shikiConfig,
           },
@@ -165,6 +169,15 @@ export default function reallySimpleDocs(options = {}) {
             },
             plugins: [
               tailwindcss(),
+              {
+                name: "reallysimpledocs-preview-scripts",
+                enforce: "pre",
+                transform(code, id) {
+                  if (!id.endsWith(".mdx") || !isInsideDir(id, docsDir)) return null;
+                  const transformed = transformPreviewScripts(code);
+                  return transformed === code ? null : { code: transformed, map: null };
+                },
+              },
               {
                 name: "reallysimpledocs-virtual-modules",
                 resolveId(id) {
@@ -211,3 +224,8 @@ export async function getMdxPage(slug) {
     },
   };
 }
+
+function isInsideDir(filePath, dir) {
+  const relative = path.relative(dir, filePath);
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}

package/src/astro/preview-scripts.js

@@ -0,0 +1,140 @@
+const previewTag = "Preview";
+const scriptTagPattern = /<script(?<attrs>[^>]*)>(?<content>[\s\S]*?)<\/script>/g;
+
+export function transformPreviewScripts(source) {
+  let output = "";
+  let cursor = 0;
+
+  while (cursor < source.length) {
+    const open = findNextTag(source, previewTag, cursor);
+    if (!open) {
+      output += source.slice(cursor);
+      break;
+    }
+
+    const close = findMatchingCloseTag(source, open);
+    if (!close) {
+      output += source.slice(cursor);
+      break;
+    }
+
+    const body = source.slice(open.end, close.start);
+    const rewrittenBody = transformPreviewScriptBody(body);
+
+    output += source.slice(cursor, open.start);
+    if (rewrittenBody === body) {
+      output += source.slice(open.start, close.end);
+    } else {
+      output += addPreviewCodeAttribute(source.slice(open.start, open.end), body);
+      output += rewrittenBody;
+      output += source.slice(close.start, close.end);
+    }
+
+    cursor = close.end;
+  }
+
+  return output;
+}
+
+function transformPreviewScriptBody(body) {
+  return body.replace(scriptTagPattern, (match, attrs = "", content = "") => {
+    if (/\ssrc\s*=/.test(attrs) || /(?:^|\s)is:inline(?:\s|=|$)/.test(attrs)) return match;
+    return `<script${attrs} is:inline>{${JSON.stringify(content)}}</script>`;
+  });
+}
+
+function addPreviewCodeAttribute(openTag, body) {
+  if (/(?:^|\s)code(?:\s|=|>)/.test(openTag)) return openTag;
+  return `${openTag.slice(0, -1)} code={${JSON.stringify(body.trim())}}>`;
+}
+
+function findMatchingCloseTag(source, open) {
+  if (open.selfClosing) return null;
+  let depth = 1;
+  let cursor = open.end;
+
+  while (cursor < source.length) {
+    const tag = findNextTag(source, previewTag, cursor);
+    if (!tag) return null;
+    if (tag.closing) depth -= 1;
+    else if (!tag.selfClosing) depth += 1;
+    if (depth === 0) return tag;
+    cursor = tag.end;
+  }
+
+  return null;
+}
+
+function findNextTag(source, name, fromIndex) {
+  let cursor = fromIndex;
+  while (cursor < source.length) {
+    const start = source.indexOf("<", cursor);
+    if (start === -1) return null;
+    if (source.startsWith("<!--", start)) {
+      const commentEnd = source.indexOf("-->", start + 4);
+      cursor = commentEnd === -1 ? source.length : commentEnd + 3;
+      continue;
+    }
+
+    const tag = readTag(source, start);
+    if (!tag) {
+      cursor = start + 1;
+      continue;
+    }
+    if (tag.name === name) return tag;
+    if (!tag.closing && !tag.selfClosing && tag.name.toLowerCase() === "script") {
+      const scriptEnd = source.toLowerCase().indexOf("</script>", tag.end);
+      cursor = scriptEnd === -1 ? source.length : scriptEnd + "</script>".length;
+      continue;
+    }
+    cursor = tag.end;
+  }
+  return null;
+}
+
+function readTag(source, start) {
+  let cursor = start + 1;
+  let closing = false;
+
+  if (source[cursor] === "/") {
+    closing = true;
+    cursor += 1;
+  }
+
+  const nameStart = cursor;
+  while (/[$A-Z_a-z0-9-]/.test(source[cursor] || "")) cursor += 1;
+  const name = source.slice(nameStart, cursor);
+  if (!name) return null;
+
+  let quote = "";
+  while (cursor < source.length) {
+    const char = source[cursor];
+    if (quote) {
+      if (char === "\\" && source[cursor + 1]) {
+        cursor += 2;
+        continue;
+      }
+      if (char === quote) quote = "";
+      cursor += 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      cursor += 1;
+      continue;
+    }
+    if (char === ">") {
+      const beforeEnd = source.slice(start, cursor).trimEnd();
+      return {
+        start,
+        end: cursor + 1,
+        name,
+        closing,
+        selfClosing: beforeEnd.endsWith("/"),
+      };
+    }
+    cursor += 1;
+  }
+
+  return null;
+}

package/src/astro/preview-source.js

@@ -1,5 +1,6 @@
 import { toMarkdown } from "mdast-util-to-markdown";
 import { mdxToMarkdown } from "mdast-util-mdx";
+import { parseCodeMeta } from "../runtime/lib/code-meta.js";
 
 export function remarkPreviewSource({ docsDir } = {}) {
   const normalizedDocsDir = docsDir ? normalizePath(docsDir).replace(/\/$/, "") : "";
@@ -7,10 +8,15 @@ export function remarkPreviewSource({ docsDir } = {}) {
   return (tree, file) => {
     if (normalizedDocsDir && !isDocsFile(file?.path, normalizedDocsDir)) return;
 
-    visit(tree, (node) => {
-      if (node?.type !== "mdxJsxFlowElement") return;
-      if (node.name === "Preview") addPreviewSource(node);
+    visit(tree, (node, parent, index) => {
+      if (node?.type === "code") return codeToMdx(node, parent, index);
+      if (node?.type !== "mdxJsxFlowElement") return null;
+      if (node.name === "Preview") {
+        addPreviewSource(node, file);
+        unwrapPreviewMarkdown(node);
+      }
       if (node.name === "Tabs") addTabsMetadata(node);
+      return null;
     });
   };
 }
@@ -24,14 +30,62 @@ function normalizePath(value) {
   return String(value || "").replaceAll("\\", "/");
 }
 
-function addPreviewSource(node) {
+function addPreviewSource(node, file) {
   node.attributes ||= [];
   if (hasAttr(node, "code")) return;
 
-  const source = toMarkdown({ type: "root", children: node.children || [] }, { extensions: [mdxToMarkdown()] }).trim();
+  const source = formatPreviewSource(getPreviewSource(node, file) ?? toMarkdown({ type: "root", children: node.children || [] }, { extensions: [mdxToMarkdown()] }));
   node.attributes.push({ type: "mdxJsxAttribute", name: "code", value: source });
 }
 
+function getPreviewSource(node, file) {
+  const value = String(file?.value || "");
+  const start = node?.position?.start?.offset;
+  const end = node?.position?.end?.offset;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || end <= start) return null;
+
+  const raw = value.slice(start, end);
+  const openEnd = raw.indexOf(">");
+  const closeStart = raw.lastIndexOf("</Preview>");
+  if (openEnd === -1 || closeStart === -1 || closeStart <= openEnd) return null;
+
+  return raw.slice(openEnd + 1, closeStart);
+}
+
+function formatPreviewSource(source) {
+  return String(source || "").trim();
+}
+
+function codeToMdx(node, parent, index) {
+  if (!parent || !Number.isInteger(index)) return null;
+  const title = parseCodeMeta(node.meta).title;
+  if (!title) return null;
+
+  return {
+    type: "mdxJsxFlowElement",
+    name: "Code",
+    attributes: [
+      { type: "mdxJsxAttribute", name: "lang", value: node.lang || "text" },
+      { type: "mdxJsxAttribute", name: "title", value: title },
+      { type: "mdxJsxAttribute", name: "code", value: String(node.value || "") },
+    ],
+    children: [],
+  };
+}
+
+function unwrapPreviewMarkdown(node) {
+  if (!Array.isArray(node?.children)) return;
+
+  const preserveDirectParagraphs =
+    (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name === "Step";
+  if (!preserveDirectParagraphs) {
+    node.children = node.children.flatMap((child) => (child?.type === "paragraph" ? child.children || [] : [child]));
+  }
+  for (const child of node.children) {
+    if (child?.type === "mdxJsxFlowElement" || child?.type === "mdxJsxTextElement") unwrapPreviewMarkdown(child);
+  }
+}
+
 function addTabsMetadata(node) {
   node.attributes ||= [];
   if (hasAttr(node, "tabs")) return;
@@ -60,10 +114,16 @@ function addTabsMetadata(node) {
   });
 }
 
-function visit(node, visitor) {
-  visitor(node);
+function visit(node, visitor, parent = null, index = -1) {
+  const replacement = visitor(node, parent, index);
+  if (replacement && parent && Number.isInteger(index)) {
+    parent.children[index] = replacement;
+    node = replacement;
+  }
   if (!Array.isArray(node?.children)) return;
-  for (const child of node.children) visit(child, visitor);
+  for (let childIndex = 0; childIndex < node.children.length; childIndex += 1) {
+    visit(node.children[childIndex], visitor, node, childIndex);
+  }
 }
 
 function getAttr(node, name) {

package/src/astro/rehype-basecoat-tables.js

@@ -0,0 +1,62 @@
+import rehypeParse from "rehype-parse";
+import rehypeStringify from "rehype-stringify";
+import { unified } from "unified";
+
+const containerClass = ["table-container", "scrollbar", "my-6"];
+const tableClass = ["table"];
+
+export function rehypeBasecoatTables() {
+  return (tree) => {
+    transformTables(tree);
+  };
+}
+
+export async function transformBasecoatTablesHtml(html) {
+  const file = await unified()
+    .use(rehypeParse, { fragment: true })
+    .use(rehypeBasecoatTables)
+    .use(rehypeStringify)
+    .process(html);
+  return String(file);
+}
+
+function transformTables(parent) {
+  if (!Array.isArray(parent?.children)) return;
+
+  for (let index = 0; index < parent.children.length; index += 1) {
+    const child = parent.children[index];
+    if (isElement(child, "table")) {
+      addClass(child, tableClass);
+      if (isTableContainer(parent)) continue;
+      parent.children[index] = {
+        type: "element",
+        tagName: "div",
+        properties: { className: [...containerClass] },
+        children: [child],
+      };
+      continue;
+    }
+    transformTables(child);
+  }
+}
+
+function isElement(node, tagName) {
+  return node?.type === "element" && node.tagName === tagName;
+}
+
+function isTableContainer(node) {
+  return isElement(node, "div") && classList(node).includes("table-container");
+}
+
+function addClass(node, classes) {
+  const merged = new Set([...classList(node), ...classes]);
+  node.properties ||= {};
+  node.properties.className = [...merged];
+}
+
+function classList(node) {
+  const value = node?.properties?.className;
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === "string") return value.split(/\s+/).filter(Boolean);
+  return [];
+}