radiant-docs 0.1.39 → 0.1.40

package/template/src/lib/mdx/remark-resolve-internal-links.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import type { Link, Root } from "mdast";
 import type { Plugin } from "unified";
@@ -6,15 +7,17 @@ import {
   getConfig,
   loadOpenApiSpec,
   type DocsConfig,
+  type HiddenPageRoute,
   type NavGroup,
   type NavMenuItem,
   type NavOpenApi,
   type NavOpenApiPage,
   type NavPage,
 } from "../validation";
+import { prependBasePath, withBasePath } from "../base-path";
 import {
   buildMdxPageHref,
-  buildOpenApiEndpointSlug,
+  buildOpenApiEndpointHref,
   parseOpenApiEndpoint,
   slugify,
 } from "../utils";
@@ -25,6 +28,7 @@ type ResolvedRouteIndex = {
   canonicalHrefByFilePath: Map<string, string>;
   allHrefsByFilePath: Map<string, string[]>;
   validRoutePaths: Set<string>;
+  allDocsFilePaths: Set<string>;
 };
 
 type LinkSplit = {
@@ -145,6 +149,38 @@ function getCurrentDocFilePath(filePath: string | undefined): string | null {
   return normalizeDocsFilePath(relativePath);
 }
 
+function collectDocsFilePaths(directory: string): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results: string[] = [];
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.name.startsWith(".") || entry.name === "node_modules") {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      results.push(...collectDocsFilePaths(entryPath));
+      continue;
+    }
+
+    if (entry.isFile() && /\.(md|mdx)$/i.test(entry.name)) {
+      const relativePath = path.relative(DOCS_ROOT, entryPath);
+      const normalizedFilePath = normalizeDocsFilePath(relativePath);
+      if (normalizedFilePath) {
+        results.push(normalizedFilePath);
+      }
+    }
+  }
+
+  return results;
+}
+
 function buildFilePathCandidates(args: {
   baseHref: string;
   currentDocFilePath: string | null;
@@ -235,11 +271,11 @@ function addMdxRoute(args: {
   }
 
   if (args.homePath && normalizedFilePath === args.homePath) {
-    addValidRoutePath(args.index, "/");
-    if (!aliases.includes("/")) {
-      aliases.unshift("/");
+    const homeHref = addValidRoutePath(args.index, prependBasePath("/"));
+    if (!aliases.includes(homeHref)) {
+      aliases.unshift(homeHref);
     }
-    args.index.canonicalHrefByFilePath.set(normalizedFilePath, "/");
+    args.index.canonicalHrefByFilePath.set(normalizedFilePath, homeHref);
   }
 
   args.index.allHrefsByFilePath.set(normalizedFilePath, aliases);
@@ -251,11 +287,33 @@ function addOpenApiEndpointRoute(args: {
   method: string;
   endpointPath: string;
 }): void {
-  const endpointSlug = buildOpenApiEndpointSlug(args.endpointPath, args.method);
-  const fullSlug = args.parentSlug
-    ? `${args.parentSlug}/${endpointSlug}`
-    : endpointSlug;
-  addValidRoutePath(args.index, fullSlug);
+  addValidRoutePath(
+    args.index,
+    buildOpenApiEndpointHref({
+      path: args.endpointPath,
+      method: args.method,
+      groupSlug: args.parentSlug,
+    }),
+  );
+}
+
+function addHiddenPageRoute(
+  index: ResolvedRouteIndex,
+  route: HiddenPageRoute,
+): void {
+  const normalizedFilePath = normalizeDocsFilePath(route.filePath);
+  if (!normalizedFilePath) return;
+
+  const href = addValidRoutePath(index, prependBasePath(route.href));
+  if (!index.canonicalHrefByFilePath.has(normalizedFilePath)) {
+    index.canonicalHrefByFilePath.set(normalizedFilePath, href);
+  }
+
+  const aliases = index.allHrefsByFilePath.get(normalizedFilePath) ?? [];
+  if (!aliases.includes(href)) {
+    aliases.push(href);
+  }
+  index.allHrefsByFilePath.set(normalizedFilePath, aliases);
 }
 
 function shouldIncludeEndpoint(
@@ -431,13 +489,20 @@ async function processMenuItems(args: {
   }
 }
 
-async function buildRouteIndex(config: DocsConfig): Promise<ResolvedRouteIndex> {
+async function buildRouteIndex(
+  config: DocsConfig,
+): Promise<ResolvedRouteIndex> {
   const index: ResolvedRouteIndex = {
     canonicalHrefByFilePath: new Map<string, string>(),
     allHrefsByFilePath: new Map<string, string[]>(),
     validRoutePaths: new Set<string>(),
+    allDocsFilePaths: new Set<string>(),
   };
 
+  for (const docFilePath of collectDocsFilePaths(DOCS_ROOT)) {
+    index.allDocsFilePaths.add(docFilePath);
+  }
+
   const homePath =
     typeof config.home === "string" ? normalizeDocsFilePath(config.home) : null;
 
@@ -459,7 +524,10 @@ async function buildRouteIndex(config: DocsConfig): Promise<ResolvedRouteIndex>
   }
 
   const rootOpenApi = (config.navigation as any).openapi;
-  if (typeof rootOpenApi === "string" || (rootOpenApi && typeof rootOpenApi === "object")) {
+  if (
+    typeof rootOpenApi === "string" ||
+    (rootOpenApi && typeof rootOpenApi === "object")
+  ) {
     await processOpenApiFile({
       index,
       parentSlug: "",
@@ -467,7 +535,10 @@ async function buildRouteIndex(config: DocsConfig): Promise<ResolvedRouteIndex>
     });
   } else if (Array.isArray(rootOpenApi)) {
     for (const openApiItem of rootOpenApi) {
-      if (typeof openApiItem !== "string" && (!openApiItem || typeof openApiItem !== "object")) {
+      if (
+        typeof openApiItem !== "string" &&
+        (!openApiItem || typeof openApiItem !== "object")
+      ) {
         continue;
       }
 
@@ -480,7 +551,11 @@ async function buildRouteIndex(config: DocsConfig): Promise<ResolvedRouteIndex>
   }
 
   if (homePath) {
-    addValidRoutePath(index, "/");
+    addValidRoutePath(index, prependBasePath("/"));
+  }
+
+  for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
+    addHiddenPageRoute(index, hiddenPageRoute);
   }
 
   return index;
@@ -501,11 +576,24 @@ function buildInvalidInternalLinkError(args: {
   baseHref: string;
   currentDocFilePath: string | null;
   filePathCandidates: string[];
+  existingFilePathCandidates: string[];
 }): Error {
   const sourceFile = args.currentDocFilePath
     ? `${args.currentDocFilePath}.mdx`
     : "the current MDX file";
 
+  if (args.existingFilePathCandidates.length > 0) {
+    const existingFiles = args.existingFilePathCandidates
+      .map((candidate) => `"${candidate}.mdx"`)
+      .join(", ");
+
+    return new Error(
+      `[USER_ERROR]: Invalid internal link "${args.baseHref}" in ${sourceFile}. ` +
+        `The target file exists (${existingFiles}), but it is not a routable docs page. ` +
+        `Add it to docs.json navigation, set it as the home page, or link to it from the navbar or footer so it is included in the built site.`,
+    );
+  }
+
   const candidateHint =
     args.filePathCandidates.length > 0
       ? ` Tried file path candidates: ${args.filePathCandidates
@@ -515,7 +603,7 @@ function buildInvalidInternalLinkError(args: {
 
   return new Error(
     `[USER_ERROR]: Invalid internal link "${args.baseHref}" in ${sourceFile}. ` +
-      `Link must match an existing docs URL or resolve to a docs page file in navigation.${candidateHint}`,
+      `No matching docs page file was found. Create the target .mdx file or update the link.${candidateHint}`,
   );
 }
 
@@ -532,12 +620,29 @@ function resolveLinkToCanonicalHref(args: {
   }
 
   const normalizedBaseRoute = normalizeRoutePath(baseHref);
+  const normalizedBaseRouteWithBase = normalizeRoutePath(
+    baseHref.startsWith("/")
+      ? withBasePath(normalizedBaseRoute)
+      : prependBasePath(normalizedBaseRoute),
+  );
+  if (args.routeIndex.validRoutePaths.has(normalizedBaseRouteWithBase)) {
+    if (
+      baseHref.startsWith("/") &&
+      normalizedBaseRoute === normalizedBaseRouteWithBase
+    ) {
+      return null;
+    }
+
+    return `${normalizedBaseRouteWithBase}${parts.suffix}`;
+  }
+
   if (args.routeIndex.validRoutePaths.has(normalizedBaseRoute)) {
-    if (baseHref.startsWith("/")) {
+    const publicRoute = normalizeRoutePath(withBasePath(normalizedBaseRoute));
+    if (baseHref.startsWith("/") && normalizedBaseRoute === publicRoute) {
       return null;
     }
 
-    return `${normalizedBaseRoute}${parts.suffix}`;
+    return `${publicRoute}${parts.suffix}`;
   }
 
   const filePathCandidates = buildFilePathCandidates({
@@ -556,14 +661,19 @@ function resolveLinkToCanonicalHref(args: {
       );
     }
 
-    return `${canonicalHref}${parts.suffix}`;
+    return `${withBasePath(canonicalHref)}${parts.suffix}`;
   }
 
   if (shouldEnforceInternalRouteValidation(baseHref)) {
+    const existingFilePathCandidates = filePathCandidates.filter((filePath) =>
+      args.routeIndex.allDocsFilePaths.has(filePath),
+    );
+
     throw buildInvalidInternalLinkError({
       baseHref,
       currentDocFilePath: args.currentDocFilePath,
       filePathCandidates,
+      existingFilePathCandidates,
     });
   }
 

package/template/src/lib/pagefind.ts

@@ -1,4 +1,5 @@
 // Pagefind TypeScript types and wrapper
+import { getDocsBasePath, withBasePath } from "./base-path";
 import { resolveStaticAssetUrl } from "./static-asset-url";
 
 export interface PagefindSearchResult {
@@ -38,11 +39,11 @@ export interface PagefindSearchResponse {
 }
 
 export interface PagefindInstance {
-  options?: (options: { baseUrl?: string; basePath?: string }) => Promise<void>;
+  options?: (options: { baseUrl?: string }) => Promise<void>;
   init: () => Promise<void>;
   search: (
     query: string,
-    options?: { filters?: Record<string, string> }
+    options?: { filters?: Record<string, string> },
   ) => Promise<PagefindSearchResponse>;
   filters: () => Promise<Record<string, Record<string, number>>>;
   preload: (query: string) => Promise<void>;
@@ -54,6 +55,57 @@ function getPagefindScriptUrl(): string {
   return resolveStaticAssetUrl("/pagefind/pagefind.js");
 }
 
+function getPagefindResultBaseUrl(): string {
+  if (typeof window === "undefined") return "/";
+
+  return `${window.location.origin}${getDocsBasePath()}`;
+}
+
+function withBasePathForSearchResultUrl(url: string): string {
+  const basePath = getDocsBasePath();
+  if (!basePath || typeof window === "undefined") {
+    return withBasePath(url);
+  }
+
+  const isAbsoluteUrl =
+    /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(url) || url.startsWith("//");
+  if (!isAbsoluteUrl) {
+    return withBasePath(url);
+  }
+
+  try {
+    const parsed = new URL(url, window.location.href);
+    if (
+      parsed.origin === window.location.origin &&
+      parsed.pathname !== basePath &&
+      !parsed.pathname.startsWith(`${basePath}/`)
+    ) {
+      const pathname = parsed.pathname.startsWith("/")
+        ? parsed.pathname
+        : `/${parsed.pathname}`;
+      parsed.pathname = `${basePath}${pathname}`;
+      return parsed.toString();
+    }
+  } catch {
+    // Fall through to normal relative URL handling.
+  }
+
+  return withBasePath(url);
+}
+
+function withBasePathForSearchResult(
+  data: PagefindResultData,
+): PagefindResultData {
+  return {
+    ...data,
+    url: withBasePathForSearchResultUrl(data.url),
+    sub_results: data.sub_results?.map((subResult) => ({
+      ...subResult,
+      url: withBasePathForSearchResultUrl(subResult.url),
+    })),
+  };
+}
+
 export async function getPagefind(): Promise<PagefindInstance | null> {
   if (pagefindInstance) return pagefindInstance;
 
@@ -62,17 +114,15 @@ export async function getPagefind(): Promise<PagefindInstance | null> {
     // This keeps Pagefind loading purely runtime and allows versioned query params.
     const importPagefind = new Function(
       "moduleUrl",
-      "return import(moduleUrl)"
+      "return import(moduleUrl)",
     ) as (moduleUrl: string) => Promise<PagefindInstance>;
 
     const pagefind = await importPagefind(getPagefindScriptUrl());
-    // Pagefind uses the script import location to derive result URL base.
-    // Since we import from the static host, force result links back to the
-    // current docs site origin while leaving asset fetches on static host.
+    // Pagefind uses the pagefind.js import URL to locate its index files.
+    // Only override result URLs; passing Pagefind's basePath would move
+    // pagefind-entry.json and chunk fetches back onto the docs origin.
     if (typeof pagefind.options === "function") {
-      const baseUrl =
-        typeof window !== "undefined" ? window.location.origin : "/";
-      await pagefind.options({ baseUrl });
+      await pagefind.options({ baseUrl: getPagefindResultBaseUrl() });
     }
     await pagefind.init();
     pagefindInstance = pagefind;
@@ -85,7 +135,7 @@ export async function getPagefind(): Promise<PagefindInstance | null> {
 
 export async function search(
   query: string,
-  limit: number = 8
+  limit: number = 8,
 ): Promise<PagefindResultData[]> {
   const pagefind = await getPagefind();
   if (!pagefind || !query.trim()) return [];
@@ -94,10 +144,8 @@ export async function search(
 
   // Load full data for top results
   const results = await Promise.all(
-    response.results.slice(0, limit).map((result) => result.data())
+    response.results.slice(0, limit).map((result) => result.data()),
   );
 
-  console.log("results", results);
-
-  return results;
+  return results.map(withBasePathForSearchResult);
 }

package/template/src/lib/routes.ts

@@ -5,6 +5,7 @@ import {
   type NavOpenApiPage,
   type NavMenuItem,
   type NavOpenApi,
+  type HiddenPageRoute,
   loadOpenApiSpec,
 } from "./validation";
 import {
@@ -21,6 +22,7 @@ type MdxNavPageItem = string | NavPage;
 export interface BaseRoute {
   slug: string;
   title: string;
+  hidden?: boolean;
 }
 
 // MDX route
@@ -95,6 +97,35 @@ function processPageItem(
   };
 }
 
+function processHiddenPageRoute(
+  route: HiddenPageRoute,
+  docs: any[],
+): MdxRoute {
+  const entry = docs.find((doc: any) => {
+    const docPath = doc.id.replace(/\.mdx$/, "");
+    return docPath === route.filePath;
+  });
+
+  if (!entry) {
+    throw new Error(
+      `Could not find content collection entry for path: ${route.filePath}`,
+    );
+  }
+
+  const slug = route.href.replace(/^\/+/, "").replace(/\/+$/, "");
+
+  return {
+    type: "mdx",
+    slug,
+    filePath: route.filePath,
+    title: resolveMdxPageTitle({
+      entry,
+      filePath: route.filePath,
+    }),
+    hidden: true,
+  };
+}
+
 type OpenApiOperationLookup = {
   method: string;
   path: string;
@@ -368,7 +399,7 @@ function assertUniqueRouteSlugs(routes: Route[]): void {
         : `openapi:${route.filePath}:${route.openApiMethod.toUpperCase()} ${route.openApiPath}`;
 
     throw new Error(
-      `Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}".`,
+      `[USER_ERROR]: Invalid docs.json: Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}". Remove one of the duplicate references or change navigation structure so each route resolves to a unique URL.`,
     );
   }
 }
@@ -405,6 +436,23 @@ export async function getAllRoutes(): Promise<Route[]> {
     }
   }
 
+  for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
+    const hiddenRoute = processHiddenPageRoute(hiddenPageRoute, docs);
+    const existingRoute = allRoutes.find(
+      (route) => route.slug === hiddenRoute.slug,
+    );
+    if (existingRoute) {
+      if (
+        existingRoute.type === "mdx" &&
+        existingRoute.filePath === hiddenRoute.filePath
+      ) {
+        continue;
+      }
+    }
+
+    allRoutes.push(hiddenRoute);
+  }
+
   assertUniqueRouteSlugs(allRoutes);
   return allRoutes;
 }

package/template/src/lib/static-asset-url.ts

@@ -1,3 +1,5 @@
+import { withBasePath } from "./base-path";
+
 type AssetsPrefixValue = string | Record<string, string> | undefined;
 
 function normalizePrefix(value: string): string {
@@ -54,7 +56,7 @@ export function resolveStaticAssetUrl(rawPath: string): string {
 
   const prefix = resolveAssetsPrefix(import.meta.env.ASSETS_PREFIX);
   if (!prefix) {
-    return `${normalizedPathname}${parsed.search}${parsed.hash}`;
+    return `${withBasePath(normalizedPathname)}${parsed.search}${parsed.hash}`;
   }
 
   const normalizedPrefixPath = `${prefix}/${normalizedPathname.replace(/^\/+/, "")}`;

package/template/src/lib/utils.ts

@@ -5,6 +5,7 @@ import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
 import rehypeExternalLinks from "./mdx/rehype-external-links";
 import path from "node:path";
+import { prependBasePath } from "./base-path";
 
 export function slugify(text: string): string {
   if (typeof text !== "string") {
@@ -66,7 +67,7 @@ export function buildMdxPageHref(args: {
   homePath?: string;
 }): string {
   if (args.homePath && args.filePath === args.homePath) {
-    return "/";
+    return prependBasePath("/");
   }
 
   const filename = path.basename(args.filePath);
@@ -75,9 +76,11 @@ export function buildMdxPageHref(args: {
     .replace(/^\/+/, "")
     .replace(/\/+$/, "");
 
-  return normalizedGroupSlug
+  const href = normalizedGroupSlug
     ? `/${normalizedGroupSlug}/${pageSlug}`
     : `/${pageSlug}`;
+
+  return prependBasePath(href);
 }
 
 export function parseOpenApiEndpoint(
@@ -103,7 +106,10 @@ export function parseOpenApiEndpoint(
   };
 }
 
-export function buildOpenApiEndpointSlug(pathStr: string, method: string): string {
+export function buildOpenApiEndpointSlug(
+  pathStr: string,
+  method: string,
+): string {
   const normalizedPath = pathStr.startsWith("/") ? pathStr : `/${pathStr}`;
   const pathSlug = normalizedPath
     .replace(/^\//, "")
@@ -123,7 +129,9 @@ export function buildOpenApiEndpointHref(args: {
     .replace(/^\/+/, "")
     .replace(/\/+$/, "");
 
-  return normalizedGroupSlug
+  const href = normalizedGroupSlug
     ? `/${normalizedGroupSlug}/${endpointSlug}`
     : `/${endpointSlug}`;
+
+  return prependBasePath(href);
 }