reallysimpledocs 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -2,12 +2,14 @@
 
 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.
 
 ## Add to an Astro site
 
+ReallySimpleDocs is an Astro integration. Add it to an existing Astro site, or create one first with `npm create astro@latest`.
+
 ```bash
-npm install reallysimpledocs@beta basecoat-css@beta tailwindcss
+npm install reallysimpledocs basecoat-css tailwindcss
 ```
 
 Add the integration:
@@ -59,49 +61,41 @@ docs/
 Welcome to the docs.
 ```
 
-reallysimpledocs 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:
+Use component overrides for layout chrome such as sidebar branding, extra head tags, or header controls between search and the built-in theme toggle:
 
-```mdx
-# Button
-
-<Callout title="MDX works">MDX is optional. Plain Markdown stays the default.</Callout>
+```js
+reallySimpleDocs({
+  components: {
+    ContentHeader: "./src/components/ContentHeader.astro",
+  },
+});
 ```
 
-## Use Basecoat on the rest of the site
+For example, put only the GitHub button in `ContentHeader`; the theme toggle stays built in.
 
-reallysimpledocs styles and scripts its generated docs pages. For custom Astro pages outside the docs route, use Basecoat directly in your own layout.
+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:
 
-Install stays the same:
+```mdx
+# Button
 
-```bash
-npm install reallysimpledocs@beta basecoat-css@beta tailwindcss
+<Callout title="MDX works">MDX is optional. Plain Markdown stays the default.</Callout>
 ```
 
-Create a site stylesheet:
-
-```css
-/* src/styles/site.css */
-@import "tailwindcss";
-@import "basecoat-css/base";
-@import "basecoat-css/styles/vega";
+## Use Basecoat outside the docs
 
-@source "../src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}";
-```
+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.
 
-Load that stylesheet and Basecoat's JavaScript in your custom layout:
+Disable managed CSS only when you want to provide the full stylesheet pipeline yourself:
 
-```astro
----
-import "../styles/site.css";
-import "basecoat-css/all.min";
----
-
-<slot />
+```js
+reallySimpleDocs({
+  css: false,
+});
 ```
 
-Use the same Basecoat `style` in your reallysimpledocs config and your site stylesheet if you want the docs and custom pages to match.
+Use `css: false` when you bring your own Tailwind/Basecoat/RSD stylesheet. ReallySimpleDocs still provides its managed JavaScript.
 
 ## Local development (this repo)
 
@@ -110,6 +104,14 @@ npm install
 npm run dev
 ```
 
+Useful checks before publishing changes:
+
+```bash
+npm run build
+npm pack --dry-run
+npm run smoke:consumer
+```
+
 ## Documentation
 
 Go to [ReallySimpleDocs.com](https://reallysimpledocs.com).

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "reallysimpledocs",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "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",
@@ -20,9 +23,9 @@
     "check": "npm run build && npm pack --dry-run && npm run smoke:consumer"
   },
   "dependencies": {
+    "@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",
@@ -30,11 +33,13 @@
     "shiki": "^4.1.0"
   },
   "peerDependencies": {
-    "basecoat-css": "^1.0.0-beta.2",
+    "astro": "^6.4.6",
+    "basecoat-css": "^1.0.0-beta.5",
     "tailwindcss": ">=4.1.17 <5"
   },
   "devDependencies": {
-    "basecoat-css": "1.0.0-beta.2",
+    "astro": "^6.4.6",
+    "basecoat-css": "^1.0.0-beta.5",
     "tailwindcss": "4.1.17"
   },
   "overrides": {

package/src/astro/index.js

@@ -2,7 +2,9 @@ import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
 import mdx from "@astrojs/mdx";
+import { unified } from "@astrojs/markdown-remark";
 import tailwindcss from "@tailwindcss/vite";
+import { remarkPreviewSource } from "./preview-source.js";
 
 const basecoatStyles = new Set(["vega", "nova", "maia", "lyra", "mira", "luma", "sera", "rhea"]);
 
@@ -26,10 +28,7 @@ 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 normalizeBoolean = (value, fallback = true) => (value === undefined ? fallback : Boolean(value));
 
 const shikiConfig = {
   themes: {
@@ -71,6 +70,7 @@ export default function reallySimpleDocs(options = {}) {
     siteFile: options.siteFile || null,
     style,
     customCss: normalizeArray(options.customCss),
+    css: normalizeBoolean(options.css),
     components: options.components || {},
     routeBase: options.routeBase ?? "/docs",
     assetsBase: options.assetsBase || "/assets",
@@ -79,7 +79,7 @@ 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");
@@ -91,27 +91,39 @@ export default function reallySimpleDocs(options = {}) {
           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:
-            normalizedOptions.components.SidebarHeader || runtimePath("components/DefaultSidebarHeader.astro"),
+        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),
@@ -142,6 +154,9 @@ export default function reallySimpleDocs(options = {}) {
             }),
           ],
           markdown: {
+            processor: unified({
+              remarkPlugins: [[remarkPreviewSource, { docsDir }]],
+            }),
             shikiConfig,
           },
           vite: {
@@ -152,34 +167,20 @@ 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";
+                  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");
@@ -195,8 +196,10 @@ export async function getMdxPage(slug) {
 }
 `;
                   }
-                  if (id === "\0virtual:reallysimpledocs/components/SidebarHeader") {
-                    return `export { default } from ${JSON.stringify(resolveUserId(components.SidebarHeader))};`;
+                  for (const [name, componentPath] of Object.entries(components)) {
+                    if (id === `\0virtual:reallysimpledocs/components/${name}`) {
+                      return `export { default } from ${JSON.stringify(resolveUserId(componentPath))};`;
+                    }
                   }
                   return null;
                 },

package/src/astro/preview-source.js

@@ -0,0 +1,90 @@
+import { toMarkdown } from "mdast-util-to-markdown";
+import { mdxToMarkdown } from "mdast-util-mdx";
+
+export function remarkPreviewSource({ docsDir } = {}) {
+  const normalizedDocsDir = docsDir ? normalizePath(docsDir).replace(/\/$/, "") : "";
+
+  return (tree, file) => {
+    if (normalizedDocsDir && !isDocsFile(file?.path, normalizedDocsDir)) return;
+
+    visit(tree, (node) => {
+      if (node?.type !== "mdxJsxFlowElement") return;
+      if (node.name === "Preview") addPreviewSource(node);
+      if (node.name === "Tabs") addTabsMetadata(node);
+    });
+  };
+}
+
+function isDocsFile(filePath, docsDir) {
+  const normalized = normalizePath(filePath || "");
+  return normalized === docsDir || normalized.startsWith(`${docsDir}/`);
+}
+
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/");
+}
+
+function addPreviewSource(node) {
+  node.attributes ||= [];
+  if (hasAttr(node, "code")) return;
+
+  const source = toMarkdown({ type: "root", children: node.children || [] }, { extensions: [mdxToMarkdown()] }).trim();
+  node.attributes.push({ type: "mdxJsxAttribute", name: "code", value: source });
+}
+
+function addTabsMetadata(node) {
+  node.attributes ||= [];
+  if (hasAttr(node, "tabs")) return;
+
+  const tabNodes = (node.children || []).filter((child) => child?.type === "mdxJsxFlowElement" && child.name === "Tab");
+  if (!tabNodes.length) return;
+
+  const seen = new Map();
+  const tabs = tabNodes.map((tab, index) => {
+    tab.attributes ||= [];
+    const title = getAttr(tab, "title") || `Tab ${index + 1}`;
+    const value = uniqueValue(slugify(title) || `tab-${index + 1}`, seen);
+    if (!hasAttr(tab, "slot")) {
+      tab.attributes.push({ type: "mdxJsxAttribute", name: "slot", value });
+    }
+    return {
+      label: title,
+      slot: value,
+    };
+  });
+
+  node.attributes.push({
+    type: "mdxJsxAttribute",
+    name: "tabs",
+    value: JSON.stringify(tabs),
+  });
+}
+
+function visit(node, visitor) {
+  visitor(node);
+  if (!Array.isArray(node?.children)) return;
+  for (const child of node.children) visit(child, visitor);
+}
+
+function getAttr(node, name) {
+  const attr = (node.attributes || []).find((item) => item.type === "mdxJsxAttribute" && item.name === name);
+  return typeof attr?.value === "string" ? attr.value : "";
+}
+
+function hasAttr(node, name) {
+  return (node.attributes || []).some((item) => item.type === "mdxJsxAttribute" && item.name === name);
+}
+
+function slugify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function uniqueValue(value, seen) {
+  const count = seen.get(value) || 0;
+  seen.set(value, count + 1);
+  return count ? `${value}-${count + 1}` : value;
+}

package/src/components/index.js

@@ -10,4 +10,5 @@ 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 Tab } from "../runtime/components/mdx/Tab.astro";
 export { default as Tabs } from "../runtime/components/mdx/Tabs.astro";