@heyo-sh/create-heyo-docs 1.0.1 → 3.0.0

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,17 +5,16 @@ import { pages as markdownPages } from "virtual:heyo-docs-content/server";
 
 export const prerender = false;
 
-export const POST: APIRoute = ({ request }) => {
-  const apiKey = process.env.OPENAI_API_KEY;
-  if (!apiKey)
+export const POST: APIRoute = async ({ request }) => {
+  if (!config.ai?.chat)
     return Response.json(
-      { error: "OPENAI_API_KEY is not configured." },
-      { status: 500 },
+      { error: "AI chat is not configured." },
+      { status: 404 },
     );
 
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
   return createAiChatResponse(request, {
     ai: config.ai,
-    auth: { type: "api-key", token: apiKey },
     markdownPages,
     pages: markdownPages.map((page) => ({
       description: page.description,

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,21 +1,20 @@
-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) {
-  const apiKey = process.env.OPENAI_API_KEY;
-  if (!apiKey)
+  if (!config.ai?.chat)
     return Response.json(
-      { error: "OPENAI_API_KEY is not configured." },
-      { status: 500 },
+      { 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,
-    auth: { type: "api-key", token: apiKey },
     markdownPages,
     pages: docsPages,
     title: config.title,

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";