radiant-docs 0.1.59 → 0.1.60

package/template/src/lib/page-description.ts

@@ -0,0 +1,20 @@
+export function normalizePageDescription(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized || undefined;
+}
+
+export function resolvePageDescription(args: {
+  pageTitle?: string;
+  pageDescription?: unknown;
+  docsTitle: string;
+}): string {
+  const explicitDescription = normalizePageDescription(args.pageDescription);
+  if (explicitDescription) return explicitDescription;
+
+  const pageTitle = args.pageTitle?.trim();
+  return pageTitle
+    ? `Learn about ${pageTitle} in the ${args.docsTitle} documentation.`
+    : `${args.docsTitle} documentation.`;
+}

package/template/src/lib/routes.ts

@@ -5,7 +5,7 @@ import {
   type NavOpenApiPage,
   type NavMenuItem,
   type NavOpenApi,
-  type HiddenPageRoute,
+  type DocsConfig,
   loadOpenApiSpec,
 } from "./validation";
 import {
@@ -50,12 +50,43 @@ export interface OpenApiRoute extends BaseRoute {
 // Discriminated union
 export type Route = MdxRoute | OpenApiRoute;
 
+type AuxiliaryPageRef = {
+  filePath: string;
+  href: string;
+};
+
+type DocsConfigWithAuxiliaryRefs = DocsConfig & {
+  auxiliaryPageRefs?: AuxiliaryPageRef[];
+};
+
 function normalizeTitle(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed.length ? trimmed : undefined;
 }
 
+function getAuxiliaryPageRefs(
+  config: DocsConfigWithAuxiliaryRefs,
+): AuxiliaryPageRef[] {
+  return config.auxiliaryPageRefs ?? [];
+}
+
+function findCanonicalMdxRoute(
+  routes: Route[],
+  filePath: string,
+): MdxRoute | undefined {
+  return (
+    routes.find(
+      (route): route is MdxRoute =>
+        route.type === "mdx" && route.filePath === filePath && !route.hidden,
+    ) ??
+    routes.find(
+      (route): route is MdxRoute =>
+        route.type === "mdx" && route.filePath === filePath,
+    )
+  );
+}
+
 export function resolveMdxPageTitle(args: {
   entry: any;
   docsTitle?: unknown;
@@ -114,33 +145,36 @@ function processPageItem(
   };
 }
 
-function processHiddenPageRoute(route: HiddenPageRoute, docs: any[]): MdxRoute {
+function processAuxiliaryPageRefRoute(
+  ref: AuxiliaryPageRef,
+  docs: any[],
+): MdxRoute {
   const entry = docs.find((doc: any) => {
     const docPath = doc.id.replace(/\.mdx$/, "");
-    return docPath === route.filePath;
+    return docPath === ref.filePath;
   });
 
   if (!entry) {
     throw new Error(
-      `Could not find content collection entry for path: ${route.filePath}`,
+      `Could not find content collection entry for path: ${ref.filePath}`,
     );
   }
 
-  const slug = route.href.replace(/^\/+/, "").replace(/\/+$/, "");
+  const slug = ref.href.replace(/^\/+/, "").replace(/\/+$/, "");
 
   return {
     type: "mdx",
     slug,
     preferredSlug: slug,
     fallbackSlug: buildMdxPageFallbackSlug({
-      filePath: route.filePath,
+      filePath: ref.filePath,
       groupSlug: "",
     }),
-    routeIdentity: `mdx:${route.filePath}`,
-    filePath: route.filePath,
+    routeIdentity: `mdx:${ref.filePath}`,
+    filePath: ref.filePath,
     title: resolveMdxPageTitle({
       entry,
-      filePath: route.filePath,
+      filePath: ref.filePath,
     }),
     hidden: true,
   };
@@ -476,8 +510,16 @@ export async function getAllRoutes(): Promise<Route[]> {
     allRoutes = allRoutes.concat(openApiRoutes);
   }
 
-  for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
-    const hiddenRoute = processHiddenPageRoute(hiddenPageRoute, docs);
+  for (const auxiliaryPageRef of getAuxiliaryPageRefs(config)) {
+    const existingFileRoute = allRoutes.find(
+      (route) =>
+        route.type === "mdx" && route.filePath === auxiliaryPageRef.filePath,
+    );
+    if (existingFileRoute) {
+      continue;
+    }
+
+    const hiddenRoute = processAuxiliaryPageRefRoute(auxiliaryPageRef, docs);
     const existingRoute = allRoutes.find(
       (route) => route.slug === hiddenRoute.slug,
     );
@@ -523,23 +565,36 @@ export async function getMdxRouteHref(args: {
   return prependBasePath(`/${route?.slug ?? preferredSlug}`);
 }
 
+async function getCanonicalMdxRouteHref(filePath: string): Promise<string> {
+  const config = await getConfig();
+  if (config.home && filePath === config.home) {
+    return prependBasePath("/");
+  }
+
+  const routes = await getAllRoutes();
+  const route = findCanonicalMdxRoute(routes, filePath);
+
+  if (route) {
+    return prependBasePath(`/${route.slug}`);
+  }
+
+  return getMdxRouteHref({ filePath });
+}
+
 export async function resolveConfiguredHref(
   href: string,
-  hiddenPageRoutes: HiddenPageRoute[] | undefined,
+  config: DocsConfigWithAuxiliaryRefs,
 ): Promise<string> {
   const normalizedHref = href.replace(/^\/+/, "").replace(/\/+$/, "");
-  const hiddenPageRoute = hiddenPageRoutes?.find(
+  const auxiliaryPageRef = getAuxiliaryPageRefs(config).find(
     (route) => route.href.replace(/^\/+/, "").replace(/\/+$/, "") === normalizedHref,
   );
 
-  if (!hiddenPageRoute) {
+  if (!auxiliaryPageRef) {
     return withBasePath(href);
   }
 
-  return getMdxRouteHref({
-    filePath: hiddenPageRoute.filePath,
-    preferredSlug: hiddenPageRoute.href,
-  });
+  return getCanonicalMdxRouteHref(auxiliaryPageRef.filePath);
 }
 
 export async function getOpenApiEndpointRouteHref(args: {

package/template/src/pages/[...slug]/index.md.ts

@@ -0,0 +1,35 @@
+import type { APIRoute } from "astro";
+import {
+  getMarkdownRoutePages,
+  MARKDOWN_CONTENT_TYPE,
+  type AiMarkdownPage,
+} from "../../lib/ai-artifacts";
+
+export async function getStaticPaths() {
+  const pages = await getMarkdownRoutePages();
+
+  return pages
+    .filter((page) => page.routeSlug)
+    .map((page) => ({
+      params: {
+        slug: page.routeSlug,
+      },
+      props: {
+        page,
+      },
+    }));
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const page = props.page as AiMarkdownPage | undefined;
+
+  if (!page) {
+    return new Response("Markdown page not found.", { status: 404 });
+  }
+
+  return new Response(page.source, {
+    headers: {
+      "Content-Type": MARKDOWN_CONTENT_TYPE,
+    },
+  });
+};

package/template/src/pages/[...spec].json.ts

@@ -0,0 +1,33 @@
+import type { APIRoute } from "astro";
+import {
+  getOpenApiSpecArtifactsByExtension,
+  readOpenApiSpecArtifact,
+  type OpenApiSpecArtifact,
+} from "../lib/ai-artifacts";
+
+export async function getStaticPaths() {
+  const specs = await getOpenApiSpecArtifactsByExtension(".json");
+
+  return specs.map((spec) => ({
+    params: {
+      spec: spec.routeParam,
+    },
+    props: {
+      spec,
+    },
+  }));
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const spec = props.spec as OpenApiSpecArtifact | undefined;
+
+  if (!spec) {
+    return new Response("OpenAPI spec not found.", { status: 404 });
+  }
+
+  return new Response(await readOpenApiSpecArtifact(spec), {
+    headers: {
+      "Content-Type": spec.contentType ?? "application/json; charset=utf-8",
+    },
+  });
+};

package/template/src/pages/[...spec].yaml.ts

@@ -0,0 +1,33 @@
+import type { APIRoute } from "astro";
+import {
+  getOpenApiSpecArtifactsByExtension,
+  readOpenApiSpecArtifact,
+  type OpenApiSpecArtifact,
+} from "../lib/ai-artifacts";
+
+export async function getStaticPaths() {
+  const specs = await getOpenApiSpecArtifactsByExtension(".yaml");
+
+  return specs.map((spec) => ({
+    params: {
+      spec: spec.routeParam,
+    },
+    props: {
+      spec,
+    },
+  }));
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const spec = props.spec as OpenApiSpecArtifact | undefined;
+
+  if (!spec) {
+    return new Response("OpenAPI spec not found.", { status: 404 });
+  }
+
+  return new Response(await readOpenApiSpecArtifact(spec), {
+    headers: {
+      "Content-Type": spec.contentType ?? "application/yaml; charset=utf-8",
+    },
+  });
+};

package/template/src/pages/[...spec].yml.ts

@@ -0,0 +1,33 @@
+import type { APIRoute } from "astro";
+import {
+  getOpenApiSpecArtifactsByExtension,
+  readOpenApiSpecArtifact,
+  type OpenApiSpecArtifact,
+} from "../lib/ai-artifacts";
+
+export async function getStaticPaths() {
+  const specs = await getOpenApiSpecArtifactsByExtension(".yml");
+
+  return specs.map((spec) => ({
+    params: {
+      spec: spec.routeParam,
+    },
+    props: {
+      spec,
+    },
+  }));
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const spec = props.spec as OpenApiSpecArtifact | undefined;
+
+  if (!spec) {
+    return new Response("OpenAPI spec not found.", { status: 404 });
+  }
+
+  return new Response(await readOpenApiSpecArtifact(spec), {
+    headers: {
+      "Content-Type": spec.contentType ?? "application/yaml; charset=utf-8",
+    },
+  });
+};

package/template/src/pages/index.md.ts

@@ -0,0 +1,17 @@
+import { getHomeMarkdownPage, MARKDOWN_CONTENT_TYPE } from "../lib/ai-artifacts";
+
+export const prerender = true;
+
+export async function GET(): Promise<Response> {
+  const page = await getHomeMarkdownPage();
+
+  if (!page) {
+    return new Response("Home page not found.", { status: 404 });
+  }
+
+  return new Response(page.source, {
+    headers: {
+      "Content-Type": MARKDOWN_CONTENT_TYPE,
+    },
+  });
+}

package/template/src/pages/llms-full.txt.ts

@@ -0,0 +1,11 @@
+import { getLlmsFullTxt, PLAIN_TEXT_CONTENT_TYPE } from "../lib/ai-artifacts";
+
+export const prerender = true;
+
+export async function GET(): Promise<Response> {
+  return new Response(await getLlmsFullTxt(), {
+    headers: {
+      "Content-Type": PLAIN_TEXT_CONTENT_TYPE,
+    },
+  });
+}

package/template/src/pages/llms.txt.ts

@@ -0,0 +1,11 @@
+import { getLlmsTxt, PLAIN_TEXT_CONTENT_TYPE } from "../lib/ai-artifacts";
+
+export const prerender = true;
+
+export async function GET(): Promise<Response> {
+  return new Response(await getLlmsTxt(), {
+    headers: {
+      "Content-Type": PLAIN_TEXT_CONTENT_TYPE,
+    },
+  });
+}

package/template/src/styles/global.css

@@ -1,5 +1,4 @@
 @import "tailwindcss";
-@import "./vaul.css";
 @plugin "@tailwindcss/typography";
 
 @theme {
@@ -31,19 +30,18 @@
     sans-serif
   );
   --font-heading: var(--rd-font-heading, var(--font-sans));
-  --font-mono:
-    var(
-      --rd-font-code,
-      "Geist Mono Variable",
-      ui-monospace,
-      SFMono-Regular,
-      Menlo,
-      Monaco,
-      Consolas,
-      "Liberation Mono",
-      "Courier New",
-      monospace
-    );
+  --font-mono: var(
+    --rd-font-code,
+    "Geist Mono Variable",
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    "Liberation Mono",
+    "Courier New",
+    monospace
+  );
 
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
@@ -143,7 +141,7 @@
 
 /* Prose styling */
 .prose-rules {
-  @apply prose max-w-none *:my-6 *:first:mt-0 *:last:mb-0 prose-h2:mt-7 prose-h2:mb-2 prose-h2:scroll-mt-24 prose-h3:mb-2 prose-h3:scroll-mt-24 prose-headings:font-semibold prose-p:mt-0 prose-p:mb-4 prose-ol:mt-0 prose-ol:mb-5 prose-ul:mt-0 prose-ul:mb-5 prose-a:decoration-(--color-theme) prose-a:decoration-from-font prose-blockquote:border-(--color-theme)/30 dark:prose-blockquote:border-(--color-theme)/30;
+  @apply prose max-w-none *:my-6 *:first:mt-0 *:last:mb-0 prose-h2:mt-12 prose-h2:mb-2 prose-h2:scroll-mt-24 prose-h3:mt-8 prose-h3:mb-2 prose-h3:scroll-mt-20 prose-headings:font-semibold prose-p:mt-0 prose-p:mb-4 prose-ol:mt-0 prose-ol:mb-5 prose-ul:mt-0 prose-ul:mb-5 prose-a:decoration-(--color-theme) prose-a:decoration-from-font prose-blockquote:border-(--color-theme)/30 dark:prose-blockquote:border-(--color-theme)/30;
   --tw-prose-body: var(--color-neutral-700);
   --tw-prose-headings: var(--color-neutral-900);
   --tw-prose-lead: var(--color-neutral-600);
@@ -191,6 +189,11 @@
   font-family: var(--font-heading);
 }
 
+.prose-rules h2 + h3 {
+  margin-block-start: 1rem;
+  margin-top: 1rem;
+}
+
 .dark .prose-rules {
   --tw-prose-body: var(--tw-prose-invert-body);
   --tw-prose-headings: var(--tw-prose-invert-headings);

package/template/src/styles/vaul.css

@@ -1,255 +0,0 @@
-[data-vaul-drawer] {
-  touch-action: none;
-  will-change: transform;
-  transition: transform 0.5s cubic-bezier(0.32, 0.72, 0, 1);
-  animation-duration: 0.5s;
-  animation-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="bottom"][data-state="open"] {
-  animation-name: slideFromBottom;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="bottom"][data-state="closed"] {
-  animation-name: slideToBottom;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="top"][data-state="open"] {
-  animation-name: slideFromTop;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="top"][data-state="closed"] {
-  animation-name: slideToTop;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="left"][data-state="open"] {
-  animation-name: slideFromLeft;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="left"][data-state="closed"] {
-  animation-name: slideToLeft;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="right"][data-state="open"] {
-  animation-name: slideFromRight;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="false"][data-vaul-drawer-direction="right"][data-state="closed"] {
-  animation-name: slideToRight;
-}
-
-[data-vaul-drawer][data-vaul-snap-points="true"][data-vaul-drawer-direction="bottom"] {
-  transform: translate3d(0, var(--initial-transform, 100%), 0);
-}
-
-[data-vaul-drawer][data-vaul-snap-points="true"][data-vaul-drawer-direction="top"] {
-  transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
-}
-
-[data-vaul-drawer][data-vaul-snap-points="true"][data-vaul-drawer-direction="left"] {
-  transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
-}
-
-[data-vaul-drawer][data-vaul-snap-points="true"][data-vaul-drawer-direction="right"] {
-  transform: translate3d(var(--initial-transform, 100%), 0, 0);
-}
-
-[data-vaul-drawer][data-vaul-delayed-snap-points="true"][data-vaul-drawer-direction="top"] {
-  transform: translate3d(0, var(--snap-point-height, 0), 0);
-}
-
-[data-vaul-drawer][data-vaul-delayed-snap-points="true"][data-vaul-drawer-direction="bottom"] {
-  transform: translate3d(0, var(--snap-point-height, 0), 0);
-}
-
-[data-vaul-drawer][data-vaul-delayed-snap-points="true"][data-vaul-drawer-direction="left"] {
-  transform: translate3d(var(--snap-point-height, 0), 0, 0);
-}
-
-[data-vaul-drawer][data-vaul-delayed-snap-points="true"][data-vaul-drawer-direction="right"] {
-  transform: translate3d(var(--snap-point-height, 0), 0, 0);
-}
-
-[data-vaul-overlay][data-vaul-snap-points="false"] {
-  animation-duration: 0.5s;
-  animation-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
-}
-
-[data-vaul-overlay][data-vaul-snap-points="false"][data-state="open"] {
-  animation-name: fadeIn;
-}
-
-[data-vaul-overlay][data-state="closed"] {
-  animation-name: fadeOut;
-}
-
-[data-vaul-animate="false"] {
-  animation: none !important;
-}
-
-[data-vaul-overlay][data-vaul-snap-points="true"] {
-  opacity: 0;
-  transition: opacity 0.5s cubic-bezier(0.32, 0.72, 0, 1);
-}
-
-[data-vaul-overlay][data-vaul-snap-points="true"] {
-  opacity: 1;
-}
-
-[data-vaul-drawer]:not([data-vaul-custom-container="true"])::after {
-  content: "";
-  position: absolute;
-  background: inherit;
-  background-color: inherit;
-}
-
-[data-vaul-drawer][data-vaul-drawer-direction="top"]::after {
-  top: initial;
-  bottom: 100%;
-  left: 0;
-  right: 0;
-  height: 200%;
-}
-
-[data-vaul-drawer][data-vaul-drawer-direction="bottom"]::after {
-  top: 100%;
-  bottom: initial;
-  left: 0;
-  right: 0;
-  height: 200%;
-}
-
-[data-vaul-drawer][data-vaul-drawer-direction="left"]::after {
-  left: initial;
-  right: 100%;
-  top: 0;
-  bottom: 0;
-  width: 200%;
-}
-
-[data-vaul-drawer][data-vaul-drawer-direction="right"]::after {
-  left: 100%;
-  right: initial;
-  top: 0;
-  bottom: 0;
-  width: 200%;
-}
-
-[data-vaul-overlay][data-vaul-snap-points="true"]:not([data-vaul-snap-points-overlay="true"]):not(
-    [data-state="closed"]
-  ) {
-  opacity: 0;
-}
-
-[data-vaul-overlay][data-vaul-snap-points-overlay="true"] {
-  opacity: 1;
-}
-
-[data-vaul-handle] {
-  display: block;
-  position: relative;
-  opacity: 0.7;
-  background: #e2e2e4;
-  margin-left: auto;
-  margin-right: auto;
-  height: 5px;
-  width: 32px;
-  border-radius: 1rem;
-  touch-action: pan-y;
-}
-
-[data-vaul-handle]:hover,
-[data-vaul-handle]:active {
-  opacity: 1;
-}
-
-[data-vaul-handle-hitarea] {
-  position: absolute;
-  left: 50%;
-  top: 50%;
-  transform: translate(-50%, -50%);
-  width: max(100%, 2.75rem);
-  height: max(100%, 2.75rem);
-  touch-action: inherit;
-}
-
-@media (hover: hover) and (pointer: fine) {
-  [data-vaul-drawer] {
-    user-select: none;
-  }
-}
-
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-@keyframes fadeOut {
-  to {
-    opacity: 0;
-  }
-}
-
-@keyframes slideFromBottom {
-  from {
-    transform: translate3d(0, var(--initial-transform, 100%), 0);
-  }
-  to {
-    transform: translate3d(0, 0, 0);
-  }
-}
-
-@keyframes slideToBottom {
-  to {
-    transform: translate3d(0, var(--initial-transform, 100%), 0);
-  }
-}
-
-@keyframes slideFromTop {
-  from {
-    transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
-  }
-  to {
-    transform: translate3d(0, 0, 0);
-  }
-}
-
-@keyframes slideToTop {
-  to {
-    transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
-  }
-}
-
-@keyframes slideFromLeft {
-  from {
-    transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
-  }
-  to {
-    transform: translate3d(0, 0, 0);
-  }
-}
-
-@keyframes slideToLeft {
-  to {
-    transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
-  }
-}
-
-@keyframes slideFromRight {
-  from {
-    transform: translate3d(var(--initial-transform, 100%), 0, 0);
-  }
-  to {
-    transform: translate3d(0, 0, 0);
-  }
-}
-
-@keyframes slideToRight {
-  to {
-    transform: translate3d(var(--initial-transform, 100%), 0, 0);
-  }
-}