reallysimpledocs 1.0.0-beta.4 → 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 gives you a shadcn/ui-compatible docs template without a React runtime. It uses Basecoat for the same design language and CSS-variable model, while staying close to plain Astro, Markdown, HTML, CSS, and a small amount of vanilla JavaScript.
+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.
 
-Docs stay portable: content lives in `docs/`, navigation lives in `docs/docs.json`, and the Astro integration owns the docs UI.
+## Install
 
-## Add to an Astro site
+Add ReallySimpleDocs to an Astro site:
 
 ```bash
-npm install reallysimpledocs@beta basecoat-css@beta 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,68 +60,89 @@ 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 `.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:
+- 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.
 
-```mdx
-# Button
+## Customization
 
-<Callout title="MDX works">MDX is optional. Plain Markdown stays the default.</Callout>
-```
+Use `components.ContentHeader` for controls between search and the built-in theme toggle:
 
-## Use Basecoat on the rest of the site
+```js
+reallySimpleDocs({
+  components: {
+    ContentHeader: "./src/components/ContentHeader.astro",
+  },
+});
+```
 
-ReallySimpleDocs styles and scripts its generated docs pages. For custom Astro pages outside the docs route, such as a landing page or app page, use Basecoat directly in your own layout.
+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.
 
-Install stays the same:
+Use `customCss` for project CSS imported after Basecoat and RSD styles:
 
-```bash
-npm install reallysimpledocs@beta basecoat-css@beta tailwindcss
+```js
+reallySimpleDocs({
+  style: "nova",
+  customCss: ["./src/docs.css"],
+});
 ```
 
-Create a site stylesheet:
+Use `css: false` only when you provide the full Tailwind/Basecoat/RSD stylesheet pipeline yourself. RSD exports its own CSS for that case:
 
 ```css
-/* src/styles/site.css */
-@import "tailwindcss";
-@import "basecoat-css/base";
-@import "basecoat-css/styles/vega";
-
-@source "../src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}";
+@import "reallysimpledocs/css";
+@import "reallysimpledocs/css/styles/vega";
 ```
 
-Load that stylesheet and Basecoat's JavaScript in your custom layout:
+## Search outside docs
+
+Render the exported `CommandDialog` on any Astro page where you want docs search:
 
 ```astro
 ---
-import "../styles/site.css";
-import "basecoat-css/all.min";
+import { CommandDialog } from "reallysimpledocs/components";
 ---
 
-<slot />
-```
+<CommandDialog />
 
-Use the same Basecoat `style` in your ReallySimpleDocs config and your site stylesheet if you want the docs and custom pages to match.
+<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:
+
+```bash
+npm run build
+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](https://github.com/hunvreus/reallysimpledocs/blob/main/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](https://github.com/hunvreus/reallysimpledocs/blob/main/LICENSE.md)
+[MIT](LICENSE.md)

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "reallysimpledocs",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./astro": "./src/astro/index.js",
-    "./components": "./src/components/index.js"
+    "./components": "./src/components/index.js",
+    "./css": "./src/css/custom.css",
+    "./css/styles/*": "./src/css/styles/*.css",
+    "./css/styles/*.css": "./src/css/styles/*.css"
   },
   "files": [
     "src",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE.md"
   ],
   "scripts": {
@@ -24,25 +26,23 @@
     "@astrojs/markdown-remark": "^7.2.0",
     "@astrojs/mdx": "^6.0.3",
     "@tailwindcss/vite": "4.1.17",
-    "astro": "^6.4.6",
     "github-slugger": "^2.0.0",
     "lucide-static": "^0.552.0",
     "lunr": "^2.3.9",
     "marked": "^16.4.1",
-    "mdast-util-gfm": "^3.1.0",
-    "mdast-util-to-markdown": "^2.1.2",
-    "remark-gfm": "^4.0.1",
-    "remark-mdx": "^3.1.1",
-    "remark-parse": "^11.0.0",
+    "rehype-parse": "^9.0.1",
+    "rehype-stringify": "^10.0.1",
     "shiki": "^4.1.0",
     "unified": "^11.0.5"
   },
   "peerDependencies": {
-    "basecoat-css": "^1.0.0-beta.2",
+    "astro": "^6.4.6",
+    "basecoat-css": "^1.0.0-beta.6",
     "tailwindcss": ">=4.1.17 <5"
   },
   "devDependencies": {
-    "basecoat-css": "1.0.0-beta.2",
+    "astro": "^6.4.6",
+    "basecoat-css": "^1.0.0-beta.6",
     "tailwindcss": "4.1.17"
   },
   "overrides": {

package/src/astro/index.js

@@ -1,10 +1,12 @@
 import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
-import { unified as astroMarkdown } from "@astrojs/markdown-remark";
 import mdx from "@astrojs/mdx";
+import { unified } from "@astrojs/markdown-remark";
 import tailwindcss from "@tailwindcss/vite";
-import { previewSourceRemarkPlugin } from "../runtime/lib/preview-source-plugin.js";
+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"]);
 
@@ -28,12 +30,7 @@ const normalizeArray = (value) => (Array.isArray(value) ? value : value ? [value
 
 const normalizeImportPath = (filePath) => filePath.replaceAll(path.sep, "/");
 
-const normalizeRecord = (value) => (value && typeof value === "object" && !Array.isArray(value) ? value : {});
-
-const isInsideDir = (dir, file) => {
-  const relative = path.relative(dir, file);
-  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
-};
+const normalizeBoolean = (value, fallback = true) => (value === undefined ? fallback : Boolean(value));
 
 const shikiConfig = {
   themes: {
@@ -63,18 +60,6 @@ function collectMdxModules(docsDir) {
   return modules;
 }
 
-function componentModuleSource(modules) {
-  const entries = Object.entries(modules);
-  const imports = entries
-    .map(([name, moduleId], index) => `import component${index} from ${JSON.stringify(moduleId)};`)
-    .join("\n");
-  return `${imports}
-export default {
-${entries.map(([name], index) => `  ${JSON.stringify(name)}: component${index},`).join("\n")}
-};
-`;
-}
-
 export default function reallySimpleDocs(options = {}) {
   const style = options.style || "vega";
   if (!basecoatStyles.has(style)) {
@@ -87,9 +72,9 @@ export default function reallySimpleDocs(options = {}) {
     siteFile: options.siteFile || null,
     style,
     customCss: normalizeArray(options.customCss),
+    css: normalizeBoolean(options.css),
+    bodyAttrs: options.bodyAttrs || {},
     components: options.components || {},
-    mdxComponents: normalizeRecord(options.mdxComponents),
-    markdownSerializers: normalizeRecord(options.markdownSerializers),
     routeBase: options.routeBase ?? "/docs",
     assetsBase: options.assetsBase || "/assets",
   };
@@ -97,57 +82,51 @@ export default function reallySimpleDocs(options = {}) {
   return {
     name: "reallysimpledocs",
     hooks: {
-      "astro:config:setup": ({ injectRoute, updateConfig, config }) => {
+      "astro:config:setup": ({ injectRoute, injectScript, updateConfig, config }) => {
         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 resolveUserId = (id) => (id?.startsWith(".") ? path.resolve(root, id) : id);
-        const markdownSerializers = Object.fromEntries(
-          Object.entries(normalizedOptions.markdownSerializers).map(([name, moduleId]) => [
-            name,
-            normalizeImportPath(resolveUserId(moduleId)),
-          ]),
-        );
-        const mdxComponents = Object.fromEntries(
-          Object.entries(normalizedOptions.mdxComponents).map(([name, moduleId]) => [
-            name,
-            normalizeImportPath(resolveUserId(moduleId)),
-          ]),
-        );
         const virtualConfig = {
           ...normalizedOptions,
           root,
           docsDir,
           siteFile: normalizedOptions.siteFile ? path.resolve(root, normalizedOptions.siteFile) : null,
-          mdxComponents,
-          markdownSerializers,
           routeBase: normalizeRouteBase(normalizedOptions.routeBase),
         };
-        const components = {
-          ContentHeader:
-            normalizedOptions.components.ContentHeader || runtimePath("components/DefaultContentHeader.astro"),
-          SidebarHeader:
-            normalizedOptions.components.SidebarHeader || runtimePath("components/DefaultSidebarHeader.astro"),
-          SidebarFooter:
-            normalizedOptions.components.SidebarFooter || runtimePath("components/DefaultSidebarFooter.astro"),
+        const mdxModules = collectMdxModules(docsDir);
+        const resolveUserId = (id) => (id?.startsWith(".") ? path.resolve(root, id) : id);
+        const componentDefaults = {
+          Head: runtimePath("components/DefaultHeadContent.astro"),
+          SidebarHeader: runtimePath("components/DefaultSidebarHeader.astro"),
+          SidebarFooter: runtimePath("components/DefaultSidebarFooter.astro"),
+          ContentHeader: runtimePath("components/DefaultContentHeader.astro"),
         };
-        fs.mkdirSync(generatedDir, { recursive: true });
-        fs.writeFileSync(
-          generatedStyles,
-          [
-            '@import "tailwindcss";',
-            '@import "basecoat-css/base";',
-            `@import "basecoat-css/styles/${style}";`,
-            `@import ${JSON.stringify(cssPath("sources.css"))};`,
-            `@import ${JSON.stringify(cssPath("custom.css"))};`,
-            `@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,mdx}"))};`,
-            "",
-          ].join("\n"),
+        const components = Object.fromEntries(
+          Object.entries(componentDefaults).map(([name, defaultPath]) => [
+            name,
+            normalizedOptions.components[name] || defaultPath,
+          ]),
         );
+        fs.mkdirSync(generatedDir, { recursive: true });
+        const styleSource = normalizedOptions.css
+          ? [
+              '@import "tailwindcss";',
+              '@import "basecoat-css/base";',
+              `@import "basecoat-css/styles/${style}";`,
+              `@import ${JSON.stringify(cssPath("custom.css"))};`,
+              `@import ${JSON.stringify(cssPath(`styles/${style}.css`))};`,
+              ...normalizedOptions.customCss.map((css) => `@import ${JSON.stringify(resolveUserId(css))};`),
+              `@source ${JSON.stringify(path.join(root, "src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"))};`,
+              `@source ${JSON.stringify(runtimePath("**/*.{astro,js,ts}"))};`,
+              `@source ${JSON.stringify(path.join(virtualConfig.docsDir, "**/*.{md,mdx}"))};`,
+              "",
+            ].join("\n")
+          : "/* ReallySimpleDocs CSS disabled by config. */\n";
+        fs.writeFileSync(generatedStyles, styleSource);
+        if (normalizedOptions.css) {
+          injectScript("page-ssr", 'import "virtual:reallysimpledocs/styles.css";');
+        }
 
         injectRoute({
           pattern: routePattern(normalizedOptions.routeBase),
@@ -178,8 +157,9 @@ export default function reallySimpleDocs(options = {}) {
             }),
           ],
           markdown: {
-            processor: astroMarkdown({
-              remarkPlugins: [previewSourceRemarkPlugin],
+            processor: unified({
+              remarkPlugins: [[remarkPreviewSource, { docsDir }]],
+              rehypePlugins: [rehypeBasecoatTables],
             }),
             shikiConfig,
           },
@@ -190,42 +170,30 @@ export default function reallySimpleDocs(options = {}) {
             plugins: [
               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();
-                  });
+                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) {
                   if (id === "virtual:reallysimpledocs/config") return "\0virtual:reallysimpledocs/config";
                   if (id === "virtual:reallysimpledocs/mdx-pages") return "\0virtual:reallysimpledocs/mdx-pages";
-                  if (id === "virtual:reallysimpledocs/mdx-components") return "\0virtual:reallysimpledocs/mdx-components";
                   if (id === "virtual:reallysimpledocs/styles.css") return generatedStyles;
-                  if (id === "virtual:reallysimpledocs/components/SidebarHeader") {
-                    return "\0virtual:reallysimpledocs/components/SidebarHeader";
-                  }
-                  if (id === "virtual:reallysimpledocs/components/SidebarFooter") {
-                    return "\0virtual:reallysimpledocs/components/SidebarFooter";
-                  }
-                  if (id === "virtual:reallysimpledocs/components/ContentHeader") {
-                    return "\0virtual:reallysimpledocs/components/ContentHeader";
+                  for (const name of Object.keys(components)) {
+                    if (id === `virtual:reallysimpledocs/components/${name}`) {
+                      return `\0virtual:reallysimpledocs/components/${name}`;
+                    }
                   }
                   return null;
                 },
                 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");
@@ -241,17 +209,10 @@ export async function getMdxPage(slug) {
 }
 `;
                   }
-                  if (id === "\0virtual:reallysimpledocs/mdx-components") {
-                    return componentModuleSource(mdxComponents);
-                  }
-                  if (id === "\0virtual:reallysimpledocs/components/SidebarHeader") {
-                    return `export { default } from ${JSON.stringify(resolveUserId(components.SidebarHeader))};`;
-                  }
-                  if (id === "\0virtual:reallysimpledocs/components/SidebarFooter") {
-                    return `export { default } from ${JSON.stringify(resolveUserId(components.SidebarFooter))};`;
-                  }
-                  if (id === "\0virtual:reallysimpledocs/components/ContentHeader") {
-                    return `export { default } from ${JSON.stringify(resolveUserId(components.ContentHeader))};`;
+                  for (const [name, componentPath] of Object.entries(components)) {
+                    if (id === `\0virtual:reallysimpledocs/components/${name}`) {
+                      return `export { default } from ${JSON.stringify(resolveUserId(componentPath))};`;
+                    }
                   }
                   return null;
                 },
@@ -263,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;
+}