radiant-docs 0.1.56 → 0.1.58

package/dist/index.js

@@ -36,7 +36,7 @@ var log = {
   ),
   blank: () => console.log("")
 };
-var SUPPORTED_COMMANDS = /* @__PURE__ */ new Set(["dev", "check", "prepare"]);
+var SUPPORTED_COMMANDS = /* @__PURE__ */ new Set(["dev"]);
 function getUserDocsDir() {
   return process.cwd();
 }
@@ -187,66 +187,6 @@ async function runAstroSync(cacheDir) {
   } catch {
   }
 }
-function toCommandOutput(value) {
-  if (!value) return "";
-  if (Buffer.isBuffer(value)) return value.toString("utf-8");
-  return String(value);
-}
-function getCommandOutput(error) {
-  return [
-    toCommandOutput(error?.stdout),
-    toCommandOutput(error?.stderr),
-    toCommandOutput(error?.message)
-  ].filter(Boolean).join("\n");
-}
-function extractUserErrors(output) {
-  const errors = [];
-  for (const line of output.split("\n")) {
-    if (!line.includes("[USER_ERROR]")) continue;
-    const message = line.split("[USER_ERROR]:")[1]?.trim() || line.trim();
-    if (message && !errors.includes(message)) {
-      errors.push(message);
-    }
-  }
-  return errors;
-}
-function getOutputTail(output, maxLines = 40) {
-  return output.split("\n").map((line) => line.trim()).filter(Boolean).slice(-maxLines).join("\n");
-}
-function runFrameworkCheck(cacheDir) {
-  log.info("Checking documentation...");
-  try {
-    execSync("npm run check", {
-      cwd: cacheDir,
-      stdio: "pipe",
-      env: {
-        ...process.env,
-        RADIANT_CHECK: "1"
-      },
-      encoding: "utf-8"
-    });
-    log.success("Documentation check passed.");
-  } catch (error) {
-    const output = getCommandOutput(error);
-    const userErrors = extractUserErrors(output);
-    log.blank();
-    log.error("Documentation check failed.");
-    if (userErrors.length > 0) {
-      log.blank();
-      for (const userError of userErrors) {
-        log.error(userError);
-      }
-    } else {
-      const outputTail = getOutputTail(output);
-      if (outputTail) {
-        log.blank();
-        console.log(outputTail);
-      }
-    }
-    log.blank();
-    process.exit(typeof error?.status === "number" ? error.status : 1);
-  }
-}
 function startDevServer(cacheDir) {
   const child = spawn("npm", ["run", "dev"], {
     cwd: cacheDir,
@@ -352,14 +292,12 @@ ${colors.bright}${colors.cyan}\u25C6 Radiant${colors.reset} v${VERSION}
 ${colors.bright}Usage:${colors.reset}
   radiant              Start the dev server
   radiant dev          Start the dev server
-  radiant check        Validate and build the docs once
-  radiant prepare      Prepare cached framework dependencies
   radiant --help       Show this help message
   radiant --version    Show version
 
 ${colors.bright}Description:${colors.reset}
   Run this command from your documentation folder (containing docs.json)
-  to preview your docs locally with hot reload, or run a one-time check.
+  to preview your docs locally with hot reload.
 `);
 }
 async function run() {
@@ -386,24 +324,13 @@ async function run() {
   const docsDir = getUserDocsDir();
   const cacheDir = getCacheDir(docsDir);
   const contentDir = getContentDir(cacheDir);
-  if (command !== "prepare") {
-    await validateUserDocs(docsDir);
-  }
+  await validateUserDocs(docsDir);
   const needsInstall = await setupCache(cacheDir);
   if (needsInstall) {
     await installDependencies(cacheDir);
   }
-  if (command === "prepare") {
-    log.success("Radiant framework cache is ready.");
-    return;
-  }
   log.info("Syncing your documentation...");
   await syncContent(docsDir, contentDir);
-  if (command === "check") {
-    log.success("Content synced.");
-    runFrameworkCheck(cacheDir);
-    return;
-  }
   await runAstroSync(cacheDir);
   log.success("Content synced.");
   log.info("Starting dev server...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {
@@ -11,9 +11,7 @@
     "build": "tsup src/index.ts --format esm --clean && npm run bundle-template",
     "dev": "tsup src/index.ts --format esm --watch",
     "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish",
-    "sync-docs-agent-version": "node scripts/sync-docs-agent-version.js",
-    "version": "npm run sync-docs-agent-version && git add ../workers/docs-agent/container/Dockerfile"
+    "release": "npm version patch && npm publish"
   },
   "dependencies": {
     "chokidar": "^4.0.3",

package/template/astro.config.mjs

@@ -8,7 +8,11 @@ import preact from "@astrojs/preact";
 import icon from "astro-icon";
 import fs from "fs";
 import path from "path";
-import { getConfig, validateMdxContent } from "./src/lib/validation";
+import {
+  getConfig,
+  isPublishableStaticAssetPath,
+  validateMdxContent,
+} from "./src/lib/validation";
 import remarkCodeBlockComponent from "./src/lib/mdx/remark-code-block-component";
 import remarkDemoteH1 from "./src/lib/mdx/remark-demote-h1";
 import remarkResolveInternalLinks from "./src/lib/mdx/remark-resolve-internal-links";
@@ -69,12 +73,10 @@ const headingAnchorContent = {
 };
 
 const shouldValidateDocs =
-  process.env.npm_lifecycle_event === "build" ||
-  process.env.npm_lifecycle_event === "check" ||
-  process.env.RADIANT_CHECK === "1";
+  process.env.npm_lifecycle_event === "build";
 
 if (shouldValidateDocs) {
-  // Run validation before Astro's internal validation for build/check commands.
+  // Run validation before Astro's internal validation for builds.
   try {
     await getConfig();
     await validateMdxContent();
@@ -91,24 +93,12 @@ function copyContentAssets() {
   const DOCS_DIR = path.join(CWD, "src/content/docs");
   const PUBLIC_DIR = path.join(CWD, "public");
 
-  const imageExtensions = [
-    ".svg",
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".webp",
-    ".gif",
-    ".avif",
-    ".ico",
-  ];
-
   function shouldCopyFile(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
-    return imageExtensions.includes(ext);
+    return isPublishableStaticAssetPath(filePath);
   }
 
-  // Build a set of all image file paths in src/content/docs
-  function collectImagePaths(dir, baseDir, pathSet) {
+  // Build a set of all publishable asset paths in src/content/docs
+  function collectAssetPaths(dir, baseDir, pathSet) {
     if (!fs.existsSync(dir)) return;
 
     const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -120,7 +110,7 @@ function copyContentAssets() {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
 
       if (entry.isDirectory()) {
-        collectImagePaths(entryPath, baseDir, pathSet);
+        collectAssetPaths(entryPath, baseDir, pathSet);
       } else if (entry.isFile() && shouldCopyFile(entryPath)) {
         // Store relative path from baseDir
         const relativePath = path.relative(baseDir, entryPath);
@@ -213,15 +203,15 @@ function copyContentAssets() {
   function syncAssets() {
     if (!fs.existsSync(DOCS_DIR)) return;
 
-    // Step 1: Collect all valid image paths from source
-    const validImagePaths = new Set();
-    collectImagePaths(DOCS_DIR, DOCS_DIR, validImagePaths);
+    // Step 1: Collect all valid asset paths from source
+    const validAssetPaths = new Set();
+    collectAssetPaths(DOCS_DIR, DOCS_DIR, validAssetPaths);
 
-    // Step 2: Copy all images from source to public
+    // Step 2: Copy all publishable assets from source to public
     copyDirectory(DOCS_DIR, PUBLIC_DIR);
 
     // Step 3: Delete orphaned files in public
-    deleteOrphanedFiles(PUBLIC_DIR, PUBLIC_DIR, validImagePaths);
+    deleteOrphanedFiles(PUBLIC_DIR, PUBLIC_DIR, validAssetPaths);
 
     // Step 4: Clean up empty directories
     cleanupEmptyDirs(PUBLIC_DIR, PUBLIC_DIR);

package/template/package-lock.json

@@ -43,6 +43,7 @@
         "preact": "^10.29.0",
         "prism-themes": "^1.9.0",
         "prismjs": "^1.30.0",
+        "radiant-docs-validator": "^0.1.17",
         "rehype-autolink-headings": "^7.1.0",
         "rehype-slug": "^6.0.0",
         "remark-gfm": "^4.0.1",
@@ -11631,6 +11632,23 @@
       ],
       "license": "MIT"
     },
+    "node_modules/radiant-docs-validator": {
+      "version": "0.1.17",
+      "resolved": "https://registry.npmjs.org/radiant-docs-validator/-/radiant-docs-validator-0.1.17.tgz",
+      "integrity": "sha512-r7+1M//tK7Iuk0J56BgQca+a+NNHWAywl+m7OkTu/oFYPHawZ4MEoCdoq3pbKnTVaZ6Fgxiz5PmrqgwL4rb1Rw==",
+      "license": "MIT",
+      "dependencies": {
+        "@iconify-json/fluent": "^1.2.47",
+        "@iconify-json/lucide": "^1.2.79",
+        "@iconify-json/simple-icons": "^1.2.69",
+        "@mdx-js/mdx": "^3.1.1",
+        "@stoplight/spectral-core": "^1.20.0",
+        "@stoplight/spectral-rulesets": "^1.22.0",
+        "shiki": "^3.20.0",
+        "yaml": "^2.8.2",
+        "zod": "^3.25.76"
+      }
+    },
     "node_modules/radix3": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.1.2.tgz",

package/template/package.json

@@ -5,7 +5,6 @@
   "scripts": {
     "dev": "astro dev",
     "start": "tsx runner.ts",
-    "check": "astro build",
     "prebuild": "rm -rf public/pagefind",
     "build": "astro build && node scripts/remove-assistant-for-non-pro.mjs && node scripts/generate-og-metadata.mjs && node scripts/generate-og-images.mjs && node scripts/stamp-og-image-versions.mjs && node scripts/stamp-image-versions.mjs && pagefind --site dist && node scripts/stamp-pagefind-runtime-version.mjs && node scripts/generate-proxy-allowed-origins.mjs && node scripts/generate-robots-txt.mjs",
     "preview": "astro preview",
@@ -48,6 +47,7 @@
     "preact": "^10.29.0",
     "prism-themes": "^1.9.0",
     "prismjs": "^1.30.0",
+    "radiant-docs-validator": "^0.1.17",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",

package/template/src/components/Footer.astro

@@ -2,7 +2,7 @@
 import Icon from "./ui/Icon.astro";
 import { getConfig } from "../lib/validation";
 import LogoLink from "./LogoLink.astro";
-import { withBasePath } from "../lib/base-path";
+import { resolveConfiguredHref } from "../lib/routes";
 
 interface Props {
   askAiEnabled?: boolean;
@@ -33,6 +33,15 @@ const socialIcons: Record<string, string> = {
   reddit: "simple-icons:reddit",
   podcast: "lucide:podcast",
 };
+
+const footerLinks = footer?.links
+  ? await Promise.all(
+      footer.links.map(async (link) => ({
+        ...link,
+        href: await resolveConfiguredHref(link.href, config.hiddenPageRoutes),
+      })),
+    )
+  : [];
 ---
 
 <footer class="border-t border-border-light pt-16" data-pagefind-ignore>
@@ -63,11 +72,11 @@ const socialIcons: Record<string, string> = {
       )
     }
     {
-      footer.links && (
+      footerLinks.length > 0 && (
         <div class="flex flex-wrap justify-center gap-x-8 gap-y-3">
-          {footer.links.map((link) => (
+          {footerLinks.map((link) => (
             <a
-              href={withBasePath(link.href)}
+              href={link.href}
               class="text-sm text-neutral-500 hover:text-neutral-900 dark:text-neutral-400 dark:hover:text-neutral-100 transition-colors duration-300"
             >
               {link.text}

package/template/src/components/Header.astro

@@ -3,7 +3,7 @@ import Icon from "./ui/Icon.astro";
 import { getConfig, type ThemeColorByMode } from "../lib/validation";
 import Search from "./Search.astro";
 import LogoLink from "./LogoLink.astro";
-import { withBasePath } from "../lib/base-path";
+import { resolveConfiguredHref } from "../lib/routes";
 import { getAssistantPanelRuntimeConfig } from "../lib/assistant-panel-config";
 import {
   getDocsBaseColorShade,
@@ -108,6 +108,26 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
       )}`,
     ].join("; ")
   : "";
+const navbarLinks = config.navbar?.links
+  ? await Promise.all(
+      config.navbar.links.map(async (link) => ({
+        ...link,
+        href: await resolveConfiguredHref(link.href, config.hiddenPageRoutes),
+      })),
+    )
+  : [];
+const navbarSecondaryHref = config.navbar?.secondary
+  ? await resolveConfiguredHref(
+      config.navbar.secondary.href,
+      config.hiddenPageRoutes,
+    )
+  : "";
+const navbarPrimaryHref = config.navbar?.primary
+  ? await resolveConfiguredHref(
+      config.navbar.primary.href,
+      config.hiddenPageRoutes,
+    )
+  : "";
 ---
 
 <header
@@ -176,7 +196,7 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
         {
           config.navbar && (
             <nav class="hidden xs:flex items-center gap-3">
-              {config.navbar.links && (
+              {navbarLinks.length > 0 && (
                 <div
                   class:list={[
                     "space-x-1",
@@ -185,7 +205,7 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
                       : "hidden lg:flex",
                   ]}
                 >
-                  {config.navbar.links.map((l, i, a) => (
+                  {navbarLinks.map((l, i, a) => (
                     <a
                       class:list={[
                         "items-center gap-1 text-[13px] font-[450] dark:font-normal text-neutral-600/85 hover:text-neutral-600 dark:text-neutral-200/90 dark:hover:text-neutral-200 duration-200 px-1.5 py-[5px] whitespace-nowrap",
@@ -193,7 +213,7 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
                           ? "hidden 2xl:flex"
                           : "flex",
                       ]}
-                      href={withBasePath(l.href)}
+                      href={l.href}
                     >
                       {l.icon && (
                         <Icon
@@ -214,7 +234,7 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
                     "h-[33px] items-center gap-1.5 px-[11px] text-[13px] bg-linear-to-br from-neutral-100/70 to-neutral-100/90 dark:bg-none dark:bg-neutral-800/80 text-neutral-900/85 hover:text-neutral-600 dark:text-neutral-200/95 dark:hover:text-neutral-200 rounded-lg [corner-shape:superellipse(1.2)] border-[0.5px] border-neutral-900/10 dark:border-white/5 transition-all whitespace-nowrap",
                     config.navbar.primary ? "hidden lg:flex" : "flex",
                   ]}
-                  href={withBasePath(config.navbar.secondary.href)}
+                  href={navbarSecondaryHref}
                 >
                   {config.navbar.secondary.icon && (
                     <Icon
@@ -233,7 +253,7 @@ const navbarPrimaryButtonStyle = navbarPrimaryThemeColors
                     "navbar-primary-trigger font-[350] dark:font-[450] h-8 flex items-center gap-2 px-3 text-[13px] rounded-lg [corner-shape:superellipse(1.2)] duration-200 transition-all whitespace-nowrap hover:opacity-95",
                   ]}
                   style={navbarPrimaryButtonStyle}
-                  href={withBasePath(config.navbar.primary.href)}
+                  href={navbarPrimaryHref}
                 >
                   {config.navbar.primary.icon && (
                     <Icon

package/template/src/components/SidebarLink.astro

@@ -1,5 +1,6 @@
 ---
-import { buildMdxPageHref, deriveTitleFromEntryId } from "../lib/utils";
+import { deriveTitleFromEntryId } from "../lib/utils";
+import { getMdxRouteHref } from "../lib/routes";
 import Icon from "./ui/Icon.astro";
 import Tag from "./ui/Tag.astro";
 import { getCollection } from "astro:content";
@@ -37,7 +38,7 @@ if (!entry) {
 // Use title from docs.json config if provided, otherwise derive from entry id
 const text = configTitle || deriveTitleFromEntryId(entry.id);
 
-const href = buildMdxPageHref({
+const href = await getMdxRouteHref({
   filePath,
   groupSlug,
   homePath: config.home,

package/template/src/components/SidebarSubgroup.astro

@@ -2,12 +2,8 @@
 import { getConfig, type NavGroup } from "../lib/validation";
 import SidebarLink from "./SidebarLink.astro";
 import SidebarOpenApiPageLink from "./sidebar/SidebarOpenApiPageLink.astro";
-import {
-  buildMdxPageHref,
-  buildOpenApiEndpointHref,
-  parseOpenApiEndpoint,
-  slugify,
-} from "../lib/utils";
+import { parseOpenApiEndpoint, slugify } from "../lib/utils";
+import { getMdxRouteHref, getOpenApiEndpointRouteHref } from "../lib/routes";
 import Tag from "./ui/Tag.astro";
 import Icon from "./ui/Icon.astro";
 
@@ -26,17 +22,18 @@ const groupId = `group-${currentPrefix}`;
 const listId = `list-${groupId}`;
 
 // Check if any child page is active (shallow check, no recursion needed)
-const containsActivePage = item.pages.some((child) => {
+let containsActivePage = false;
+for (const child of item.pages) {
   let href: string | null = null;
 
   if (typeof child === "string") {
-    href = buildMdxPageHref({
+    href = await getMdxRouteHref({
       filePath: child,
       groupSlug: currentPrefix,
       homePath: config.home,
     });
   } else if ("page" in child) {
-    href = buildMdxPageHref({
+    href = await getMdxRouteHref({
       filePath: child.page,
       groupSlug: currentPrefix,
       homePath: config.home,
@@ -44,7 +41,8 @@ const containsActivePage = item.pages.some((child) => {
   } else if ("openapi" in child) {
     const parsedEndpoint = parseOpenApiEndpoint(child.openapi.endpoint);
     if (parsedEndpoint) {
-      href = buildOpenApiEndpointHref({
+      href = await getOpenApiEndpointRouteHref({
+        source: child.openapi.source,
         path: parsedEndpoint.path,
         method: parsedEndpoint.method,
         groupSlug: currentPrefix,
@@ -52,13 +50,16 @@ const containsActivePage = item.pages.some((child) => {
     }
   }
 
-  if (!href) return false;
+  if (!href) continue;
 
   // Normalize paths for comparison (remove trailing slashes)
   const normalizedCurrent = Astro.url.pathname.replace(/\/$/, "");
   const normalizedTarget = href.replace(/\/$/, "");
-  return normalizedCurrent === normalizedTarget;
-});
+  if (normalizedCurrent === normalizedTarget) {
+    containsActivePage = true;
+    break;
+  }
+}
 ---
 
 <div

package/template/src/components/sidebar/SidebarEndpointLink.astro

@@ -1,10 +1,11 @@
 ---
 import Tag from "../ui/Tag.astro";
-import { buildOpenApiEndpointHref } from "../../lib/utils";
 import { methodColors } from "../../lib/utils";
+import { getOpenApiEndpointRouteHref } from "../../lib/routes";
 import type { NavTag } from "../../lib/validation";
 
 interface Props {
+  source: string;
   method: string;
   path: string;
   summary?: string;
@@ -13,10 +14,19 @@ interface Props {
   parentSlug?: string;
 }
 
-const { method, path: pathStr, summary, title, tag, parentSlug = "" } = Astro.props;
+const {
+  source,
+  method,
+  path: pathStr,
+  summary,
+  title,
+  tag,
+  parentSlug = "",
+} = Astro.props;
 
 const normalizedMethod = method.toLowerCase();
-const href = buildOpenApiEndpointHref({
+const href = await getOpenApiEndpointRouteHref({
+  source,
   path: pathStr,
   method: normalizedMethod,
   groupSlug: parentSlug,

package/template/src/components/sidebar/SidebarOpenApi.astro

@@ -182,6 +182,7 @@ const sortedTagGroups: TagGroup[] = Array.from(tagGroups.entries())
               {group.endpoints.map((endpoint) => (
                 <li>
                   <SidebarEndpointLink
+                    source={openApiPath}
                     method={endpoint.method}
                     path={endpoint.path}
                     summary={endpoint.summary}
@@ -196,6 +197,7 @@ const sortedTagGroups: TagGroup[] = Array.from(tagGroups.entries())
         untaggedEndpoints.map((endpoint, index) => (
           <li>
             <SidebarEndpointLink
+              source={openApiPath}
               method={endpoint.method}
               path={endpoint.path}
               summary={endpoint.summary}

package/template/src/components/sidebar/SidebarOpenApiPageLink.astro

@@ -47,6 +47,7 @@ if (!matchedPath) {
 ---
 
 <SidebarEndpointLink
+  source={item.openapi.source}
   method={endpointMethod}
   path={matchedPath}
   summary={endpointSummary}

package/template/src/components/user/Accordion.astro

@@ -1,6 +1,5 @@
 ---
 import Icon from "../ui/Icon.astro";
-import { validateProps } from "../../lib/component-error";
 
 interface Props {
   title: string;
@@ -19,18 +18,6 @@ const TITLE_SIZE_CLASS = {
   xl: "text-xl",
   "2xl": "text-2xl",
 } as const;
-
-validateProps(
-  "Accordion",
-  { title, icon, defaultOpen, titleSize },
-  {
-    title: { required: true, type: "string" },
-    icon: { type: "string" },
-    defaultOpen: { type: "boolean" },
-    titleSize: { enum: ["xs", "sm", "md", "lg", "xl", "2xl"] },
-  },
-  Astro.url.pathname,
-);
 ---
 
 <div

package/template/src/components/user/Callout.astro

@@ -1,6 +1,5 @@
 ---
 import Icon from "../ui/Icon.astro";
-import { validateProps } from "../../lib/component-error";
 
 type CalloutType = "warning" | "info" | "tip" | "danger" | "success";
 
@@ -43,36 +42,8 @@ const typeDefaults: Record<
   },
 };
 
-const rawProps = Astro.props as { icon?: unknown; title?: unknown };
-const rawIcon = rawProps.icon;
-const rawTitle = rawProps.title;
 const { type = "info", title, icon, accent = true, color } = Astro.props;
 
-validateProps(
-  "Callout",
-  { type, title, icon, accent, color },
-  {
-    type: { enum: ["warning", "info", "tip", "danger", "success"] },
-    title: { type: ["string", "boolean"] },
-    icon: { type: ["string", "boolean"] },
-    accent: { type: "boolean" },
-    color: { type: "string" },
-  },
-  Astro.url.pathname,
-);
-
-if (rawIcon === true) {
-  throw new Error(
-    `[USER_ERROR]: <Callout>: Invalid prop "icon": expected string or false, got true (in ${Astro.url.pathname})`,
-  );
-}
-
-if (rawTitle === true) {
-  throw new Error(
-    `[USER_ERROR]: <Callout>: Invalid prop "title": expected string or false, got true (in ${Astro.url.pathname})`,
-  );
-}
-
 const defaults = typeDefaults[type];
 const resolvedTitle = title === false ? null : (title ?? defaults.title);
 const resolvedIcon = icon === false ? null : (icon ?? defaults.icon);