@heyo-sh/create-heyo-docs 1.0.0 → 2.0.0

package/templates/astro/src/lib/openapi-request.ts

@@ -1,160 +1,20 @@
-import {
-  createDocsModel,
-  findOpenApiEndpoint,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
+import { createDocsModel } from "@heyo-sh/heyo-docs/model";
+import { handleOpenApiRequest as forwardOpenApiRequest } from "@heyo-sh/heyo-docs/openapi/request";
 
 import config from "../../heyo-docs.config";
 import { openApiDocuments } from "virtual:heyo-docs-openapi";
 import { pages } from "virtual:heyo-docs-content";
 
-interface OpenApiRequestPayload {
-  bearerToken: string;
-  body?: string;
-  endpointSlug: string;
-  parameters: Record<string, string>;
-  server: string;
-}
-
-/**
- * Sends documented API calls from the server, so browsers do not need the API
- * to expose CORS headers. Targets are limited to servers from the OpenAPI file.
- */
 export async function handleOpenApiRequest(
   request: Request,
 ): Promise<Response> {
   if (request.method !== "POST")
     return new Response("Method Not Allowed", {
-      headers: { Allow: "POST" },
       status: 405,
+      headers: { Allow: "POST" },
     });
-
-  const payload = await requestPayload(request);
-  if (!payload)
-    return new Response("Invalid OpenAPI request.", { status: 400 });
-
-  const model = createDocsModel(config, pages, openApiDocuments);
-  const endpoint = findOpenApiEndpoint(model.endpoints, payload.endpointSlug);
-  if (!endpoint) return new Response("Endpoint not found.", { status: 404 });
-  if (endpoint.servers.length && !endpoint.servers.includes(payload.server))
-    return new Response("API server is not declared in the OpenAPI schema.", {
-      status: 400,
-    });
-  if (!endpoint.servers.length && payload.server)
-    return new Response("This endpoint does not declare an API server.", {
-      status: 400,
-    });
-
-  const headers = requestHeaders(
-    endpoint,
-    payload.parameters,
-    payload.bearerToken,
-  );
-  const url = requestUrl(
-    endpoint,
-    payload.server,
-    payload.parameters,
-    request.url,
-  );
-
-  try {
-    const response = await fetch(url, {
-      method: endpoint.method.toUpperCase(),
-      headers,
-      body: payload.body,
-    });
-    const responseHeaders = new Headers();
-    const contentType = response.headers.get("content-type");
-    if (contentType) responseHeaders.set("content-type", contentType);
-    const body = [204, 205, 304].includes(response.status)
-      ? null
-      : await response.arrayBuffer();
-    return new Response(body, {
-      headers: responseHeaders,
-      status: response.status,
-      statusText: response.statusText,
-    });
-  } catch {
-    return new Response("The API server could not be reached.", {
-      status: 502,
-    });
-  }
-}
-
-async function requestPayload(
-  request: Request,
-): Promise<OpenApiRequestPayload | undefined> {
-  try {
-    const value: unknown = await request.json();
-    if (!isRecord(value)) return undefined;
-    const endpointSlug = stringValue(value.endpointSlug);
-    const server = stringValue(value.server);
-    if (!endpointSlug || server === undefined) return undefined;
-    return {
-      bearerToken: stringValue(value.bearerToken) ?? "",
-      body: stringValue(value.body),
-      endpointSlug,
-      parameters: stringRecord(value.parameters),
-      server,
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-function requestUrl(
-  endpoint: OpenApiEndpoint,
-  server: string,
-  parameters: Record<string, string>,
-  requestUrl: string,
-) {
-  let path = endpoint.path.replace(/\{([^}]+)\}/g, (match, name: string) => {
-    const value = parameters[`path:${name}`];
-    return value ? encodeURIComponent(value) : match;
-  });
-  const query = new URLSearchParams();
-  for (const parameter of endpoint.parameters) {
-    if (parameter.in !== "query") continue;
-    const value = parameters[`query:${parameter.name}`];
-    if (value) query.set(parameter.name, value);
-  }
-  const search = query.toString();
-  path = `${path}${search ? `?${search}` : ""}`;
-  return server
-    ? `${server.replace(/\/$/, "")}${path}`
-    : new URL(path, requestUrl).toString();
-}
-
-function requestHeaders(
-  endpoint: OpenApiEndpoint,
-  parameters: Record<string, string>,
-  bearerToken: string,
-) {
-  const headers = new Headers();
-  for (const parameter of endpoint.parameters) {
-    if (parameter.in !== "header") continue;
-    const value = parameters[`header:${parameter.name}`];
-    if (value) headers.set(parameter.name, value);
-  }
-  if (endpoint.requestBody?.contentType)
-    headers.set("Content-Type", endpoint.requestBody.contentType);
-  if (bearerToken) headers.set("Authorization", `Bearer ${bearerToken}`);
-  return headers;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function stringRecord(value: unknown): Record<string, string> {
-  if (!isRecord(value)) return {};
-  return Object.fromEntries(
-    Object.entries(value).filter(
-      (entry): entry is [string, string] => typeof entry[1] === "string",
-    ),
+  return forwardOpenApiRequest(
+    request,
+    createDocsModel(config, pages, openApiDocuments).endpoints,
   );
 }
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}

package/templates/astro/src/pages/[...slug].astro

@@ -2,15 +2,15 @@
 import { AstroDocsApp } from "../components/docs-app";
 import DocsLayout from "../layouts/docs-layout.astro";
 import { docsContext, pathnameForSlug } from "../lib/docs";
-import { docsSeo } from "../lib/seo";
-import { openApiEndpointDetail } from "@heyo-sh/heyo-docs";
+import { docsSeo, siteSeo } from "@heyo-sh/heyo-docs/seo";
+import { openApiEndpointDetail } from "@heyo-sh/heyo-docs/openapi";
 import { pages } from "virtual:heyo-docs-content";
 import { openApiEndpoints } from "virtual:heyo-docs-openapi/index";
 
 export async function getStaticPaths() {
-  return [...pages, ...openApiEndpoints].map(({ slug }) => ({
-    params: { slug: slug === "/" ? undefined : slug.slice(1) },
-  }));
+  return [...pages, ...openApiEndpoints]
+    .filter(({ slug }) => slug !== "/")
+    .map(({ slug }) => ({ params: { slug: slug.slice(1) } }));
 }
 
 const pathname = pathnameForSlug(Astro.params.slug);
@@ -25,16 +25,8 @@ const seo = exists
   ? docsSeo({ ...context, pathname })
   : {
       title: `Not found | ${context.config.title}`,
-      description: context.config.description,
-      structuredData: [
-        {
-          "@context": "https://schema.org",
-          "@type": "WebSite",
-          name: context.config.title,
-          description: context.config.description,
-          ...(context.config.siteUrl ? { url: context.config.siteUrl } : {}),
-        },
-      ],
+      description: siteSeo(context.config).description,
+      structuredData: siteSeo(context.config).structuredData,
     };
 ---
 

package/templates/astro/src/pages/[...slug].md.ts

@@ -1,5 +1,8 @@
 import type { APIRoute } from "astro";
-import { markdownForPage, pathnameFromMarkdownPath } from "@heyo-sh/heyo-docs";
+import {
+  markdownForPage,
+  pathnameFromMarkdownPath,
+} from "@heyo-sh/heyo-docs/llm";
 
 import { pages } from "virtual:heyo-docs-content/server";
 

package/templates/astro/src/pages/heyo-docs-internal/ai-chat.ts

@@ -1,4 +1,3 @@
-import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
 import type { APIRoute } from "astro";
 
 import config from "../../../heyo-docs.config";
@@ -6,8 +5,15 @@ import { pages as markdownPages } from "virtual:heyo-docs-content/server";
 
 export const prerender = false;
 
-export const POST: APIRoute = ({ request }) =>
-  createAiChatResponse(request, {
+export const POST: APIRoute = async ({ request }) => {
+  if (!config.ai?.chat)
+    return Response.json(
+      { error: "AI chat is not configured." },
+      { status: 404 },
+    );
+
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
+  return createAiChatResponse(request, {
     ai: config.ai,
     markdownPages,
     pages: markdownPages.map((page) => ({
@@ -18,3 +24,4 @@ export const POST: APIRoute = ({ request }) =>
     })),
     title: config.title,
   });
+};

package/templates/astro/src/pages/heyo-docs-internal/openapi-request.ts

@@ -5,4 +5,10 @@ import { handleOpenApiRequest } from "../../lib/openapi-request";
 /** The only dynamic OpenAPI surface: a same-origin proxy for Try it requests. */
 export const prerender = false;
 
+export const GET: APIRoute = () =>
+  new Response("Method Not Allowed", {
+    headers: { Allow: "POST" },
+    status: 405,
+  });
+
 export const POST: APIRoute = ({ request }) => handleOpenApiRequest(request);

package/templates/astro/src/pages/index.astro

@@ -1,13 +1,22 @@
 ---
-import { navigationPages } from "@heyo-sh/heyo-docs";
-
+import { AstroDocsApp } from "../components/docs-app";
+import DocsLayout from "../layouts/docs-layout.astro";
 import { docsContext } from "../lib/docs";
+import { docsSeo, siteSeo } from "@heyo-sh/heyo-docs/seo";
 
-const firstPage = docsContext("/")
-  .model.navigation.flatMap((group) => navigationPages(group.sections))
-  .at(0);
-
-if (!firstPage) throw new Error("No local documentation page is configured.");
-
-return Astro.redirect(firstPage.slug);
+const pathname = "/";
+const context = docsContext(pathname);
+const exists = Boolean(context.page || context.endpoint);
+if (!exists) Astro.response.status = 404;
+const seo = exists
+  ? docsSeo({ ...context, pathname })
+  : {
+      title: `Not found | ${context.config.title}`,
+      description: siteSeo(context.config).description,
+      structuredData: siteSeo(context.config).structuredData,
+    };
 ---
+
+<DocsLayout {...seo} robots={exists ? "index, follow" : "noindex"}>
+  <AstroDocsApp client:load pathname={pathname} />
+</DocsLayout>

package/templates/astro/src/pages/llms-full.txt.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from "astro";
-import { llmsFull } from "@heyo-sh/heyo-docs";
+import { llmsFull } from "@heyo-sh/heyo-docs/llm";
 
 import config from "../../heyo-docs.config";
 import { pages } from "virtual:heyo-docs-content/server";

package/templates/astro/src/pages/llms.txt.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from "astro";
-import { llmsIndex } from "@heyo-sh/heyo-docs";
+import { llmsIndex } from "@heyo-sh/heyo-docs/llm";
 
 import config from "../../heyo-docs.config";
 import { pages } from "virtual:heyo-docs-content/server";

package/templates/astro/src/pages/rss.xml.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from "astro";
-import { rssXml } from "@heyo-sh/heyo-docs";
+import { rssXml } from "@heyo-sh/heyo-docs/rss";
 
 import config from "../../heyo-docs.config";
 import { pages } from "virtual:heyo-docs-content/server";

package/templates/astro/src/pages/sitemap.xml.ts

@@ -1,8 +1,8 @@
 import type { APIRoute } from "astro";
-import { sitemapXml } from "@heyo-sh/heyo-docs";
+import { sitemapXml } from "@heyo-sh/heyo-docs/seo";
 
 import config from "../../heyo-docs.config";
-import { createDocsModel } from "@heyo-sh/heyo-docs";
+import { createDocsModel } from "@heyo-sh/heyo-docs/model";
 import { openApiDocuments } from "virtual:heyo-docs-openapi";
 import { pages } from "virtual:heyo-docs-content";
 

package/templates/astro/src/virtual.d.ts

@@ -1,26 +1,26 @@
 declare module "virtual:heyo-docs-content" {
-  import type { DocsPage } from "@heyo-sh/heyo-docs";
+  import type { DocsPage } from "@heyo-sh/heyo-docs/types";
   export const pages: DocsPage[];
 }
 
 declare module "virtual:heyo-docs-config" {
-  import type { HeyoDocsConfig } from "@heyo-sh/heyo-docs";
+  import type { HeyoDocsConfig } from "@heyo-sh/heyo-docs/types";
   export const config: HeyoDocsConfig;
 }
 
 declare module "virtual:heyo-docs-theme.css";
 
 declare module "virtual:heyo-docs-content/server" {
-  import type { MarkdownPage } from "@heyo-sh/heyo-docs";
+  import type { MarkdownPage } from "@heyo-sh/heyo-docs/types";
   export const pages: MarkdownPage[];
 }
 
 declare module "virtual:heyo-docs-openapi" {
-  import type { OpenApiDocumentSource } from "@heyo-sh/heyo-docs";
+  import type { OpenApiDocumentSource } from "@heyo-sh/heyo-docs/types";
   export const openApiDocuments: OpenApiDocumentSource[];
 }
 
 declare module "virtual:heyo-docs-openapi/index" {
-  import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs";
+  import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs/types";
   export const openApiEndpoints: OpenApiEndpoint[];
 }

package/templates/next/app/[[...slug]]/page.tsx

@@ -1,13 +1,12 @@
 import type { Metadata } from "next";
 import { notFound, redirect } from "next/navigation";
-import {
-  navigationPages,
-  openApiEndpointDetail,
-} from "@heyo-sh/heyo-docs/node";
+import { nextDocsSeo } from "@heyo-sh/heyo-docs/seo/next";
+import { navigationPages } from "@heyo-sh/heyo-docs/navigation";
+import { openApiEndpointDetail } from "@heyo-sh/heyo-docs/openapi";
+import { serializeJsonLd } from "@heyo-sh/heyo-docs/seo";
 
 import { NextDocsApp } from "../components/docs-app";
 import { docsContext, docsModel, pathnameForSegments } from "../lib/docs";
-import { docsSeo } from "../lib/seo";
 
 interface PageProps {
   params: Promise<{ slug?: string[] }>;
@@ -41,7 +40,7 @@ export async function generateMetadata({
       title: `Not found | ${context.config.title}`,
       robots: { index: false, follow: false },
     };
-  return docsSeo({ ...context, pathname }).metadata;
+  return nextDocsSeo({ ...context, pathname }).metadata;
 }
 
 export default async function DocsPage({ params }: PageProps) {
@@ -55,18 +54,20 @@ export default async function DocsPage({ params }: PageProps) {
     if (!firstPage)
       throw new Error("No local documentation page is configured.");
 
-    redirect(firstPage.slug);
+    // A minimal project owns `/` through content/index.mdx. Do not redirect
+    // the root route to itself.
+    if (firstPage.slug !== "/") redirect(firstPage.slug);
   }
   const context = docsContext(pathname);
   if (!context.page && !context.endpoint) notFound();
-  const { structuredData } = docsSeo({ ...context, pathname });
+  const { structuredData } = nextDocsSeo({ ...context, pathname });
 
   return (
     <>
       <script
         type="application/ld+json"
         dangerouslySetInnerHTML={{
-          __html: JSON.stringify(structuredData).replace(/</g, "\\u003c"),
+          __html: serializeJsonLd(structuredData),
         }}
       />
       <NextDocsApp

package/templates/next/app/components/docs-app.tsx

@@ -1,58 +1,23 @@
 "use client";
 
-import {
-  DocsApp,
-  openApiEndpointDataPath,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
-import {
-  createContext,
-  forwardRef,
-  useCallback,
-  useContext,
-  useEffect,
-  useRef,
-  useState,
-  type ComponentPropsWithoutRef,
-  type MouseEvent,
-} from "react";
+import Link from "next/link";
+import { DocsApp } from "@heyo-sh/heyo-docs";
+import type { DocsLinkProps } from "@heyo-sh/heyo-docs/link";
+import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs/types";
+import { useDocsTheme } from "@heyo-sh/heyo-docs/theme/provider";
+import { forwardRef } from "react";
+import { __HEYO_THEME_IDENTIFIER__ } from "@heyo-sh/heyo-docs/theme/__HEYO_THEME__";
 
 import { docsConfig, openApiEndpoints, pages } from "../_heyo-docs/content";
 import { iconSet } from "../heyo-docs-icons";
-import { useTheme } from "./theme-provider";
 
-type Navigate = (href: string) => void;
-
-const NextNavigationContext = createContext<Navigate | undefined>(undefined);
-
-const NextDocsLink = forwardRef<
-  HTMLAnchorElement,
-  ComponentPropsWithoutRef<"a">
->(function NextDocsLink({ href, onClick, target, ...props }, ref) {
-  const navigate = useContext(NextNavigationContext);
-
-  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
-    onClick?.(event);
-    if (
-      !navigate ||
-      event.defaultPrevented ||
-      event.button !== 0 ||
-      event.metaKey ||
-      event.altKey ||
-      event.ctrlKey ||
-      event.shiftKey ||
-      target
-    )
-      return;
-
-    event.preventDefault();
-    navigate(href ?? "/");
-  };
-
-  return (
-    <a {...props} href={href} onClick={handleClick} ref={ref} target={target} />
-  );
-});
+const NextDocsLink = forwardRef<HTMLAnchorElement, DocsLinkProps>(
+  function NextDocsLink({ href = "/", ...props }, ref) {
+    // Next owns history, RSC payloads, metadata and scroll restoration. Docs
+    // links must not emulate routing with pushState in a client component.
+    return <Link {...props} href={href} ref={ref} />;
+  },
+);
 
 export function NextDocsApp({
   currentOpenApiEndpoint,
@@ -61,78 +26,21 @@ export function NextDocsApp({
   currentOpenApiEndpoint?: OpenApiEndpoint;
   pathname: string;
 }) {
-  const { mounted, resolvedTheme, setTheme } = useTheme();
-  const [activePathname, setActivePathname] = useState(pathname);
-  const [activeOpenApiEndpoint, setActiveOpenApiEndpoint] = useState(
-    currentOpenApiEndpoint,
-  );
-  const navigationId = useRef(0);
-
-  const navigate = useCallback(async (href: string, updateHistory = true) => {
-    const destination = new URL(href, window.location.href);
-    if (destination.origin !== window.location.origin) {
-      window.location.assign(href);
-      return;
-    }
-
-    const nextPathname = destination.pathname;
-    const indexedEndpoint = openApiEndpoints.find(
-      (endpoint) => endpoint.slug === nextPathname,
-    );
-    const page = pages.find((candidate) => candidate.slug === nextPathname);
-    if (!indexedEndpoint && !page) {
-      window.location.assign(href);
-      return;
-    }
-
-    const currentNavigation = ++navigationId.current;
-    let endpoint: OpenApiEndpoint | undefined;
-    if (indexedEndpoint) {
-      const response = await fetch(
-        openApiEndpointDataPath(indexedEndpoint.slug),
-      );
-      if (!response.ok) {
-        window.location.assign(href);
-        return;
-      }
-      endpoint = (await response.json()) as OpenApiEndpoint;
-    }
-    if (currentNavigation !== navigationId.current) return;
-
-    if (updateHistory) window.history.pushState({}, "", destination);
-    document.title =
-      page?.seo.title ?? `${indexedEndpoint!.title} | ${docsConfig.title}`;
-    setActiveOpenApiEndpoint(endpoint);
-    setActivePathname(nextPathname);
-  }, []);
-
-  useEffect(() => {
-    const onPopState = () => {
-      void navigate(window.location.href, false);
-    };
-
-    window.addEventListener("popstate", onPopState);
-    return () => window.removeEventListener("popstate", onPopState);
-  }, [navigate]);
+  const { mounted, resolvedTheme, toggleTheme } = useDocsTheme();
 
   return (
-    <NextNavigationContext.Provider value={navigate}>
-      <DocsApp
-        config={docsConfig}
-        iconSet={iconSet}
-        isDark={mounted ? resolvedTheme === "dark" : undefined}
-        link={NextDocsLink}
-        onThemeToggle={
-          mounted
-            ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
-            : undefined
-        }
-        currentOpenApiEndpoint={activeOpenApiEndpoint}
-        openApiEndpoints={openApiEndpoints}
-        openApiRequestUrl="/heyo-docs-internal/openapi-request"
-        pages={pages}
-        pathname={activePathname}
-      />
-    </NextNavigationContext.Provider>
+    <DocsApp
+      config={docsConfig}
+      currentOpenApiEndpoint={currentOpenApiEndpoint}
+      iconSet={iconSet}
+      isDark={mounted ? resolvedTheme === "dark" : undefined}
+      link={NextDocsLink}
+      onThemeToggle={mounted ? toggleTheme : undefined}
+      openApiEndpoints={openApiEndpoints}
+      openApiRequestUrl="/heyo-docs-internal/openapi-request"
+      pages={pages}
+      pathname={pathname}
+      theme={__HEYO_THEME_IDENTIFIER__}
+    />
   );
 }

package/templates/next/app/heyo-docs-icons.tsx

@@ -31,7 +31,7 @@ import {
   RiStarLine,
   RiSunLine,
 } from "@remixicon/react";
-import type { IconSet } from "@heyo-sh/heyo-docs";
+import type { IconSet } from "@heyo-sh/heyo-docs/types";
 
 /** Statically selected icons keep unused packs out of the client bundle. */
 export const iconSet = {

package/templates/next/app/heyo-docs-internal/ai-chat/route.ts

@@ -1,11 +1,18 @@
-import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
-
 import config from "../../../heyo-docs.config";
 import { docsPages, markdownPages } from "../../_heyo-docs/server";
 
 export const runtime = "nodejs";
 
 export async function POST(request: Request) {
+  if (!config.ai?.chat)
+    return Response.json(
+      { error: "AI chat is not configured." },
+      { status: 404 },
+    );
+
+  // Pi's provider catalogue is a server-only optional feature. Importing it
+  // only for an enabled request keeps static docs builds free of AI runtime.
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
   return createAiChatResponse(request, {
     ai: config.ai,
     markdownPages,

package/templates/next/app/heyo-docs-internal/markdown/[[...slug]]/route.ts

@@ -1,7 +1,7 @@
 import {
   markdownForPage,
   pathnameFromMarkdownPath,
-} from "@heyo-sh/heyo-docs/node";
+} from "@heyo-sh/heyo-docs/llm";
 
 import { markdownPages } from "../../../lib/docs";