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

package/templates/react-router/app/routes/ai-chat.ts

@@ -7,10 +7,14 @@ import { pages as markdownPages } from "virtual:heyo-docs-content/server";
 export async function action({ request }: ActionFunctionArgs) {
   if (request.method !== "POST")
     return new Response("Method Not Allowed", {
-      headers: { Allow: "POST" },
       status: 405,
+      headers: { Allow: "POST" },
     });
-
+  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,

package/templates/react-router/app/routes/docs.tsx

@@ -1,12 +1,17 @@
+import { DocsApp } from "@heyo-sh/heyo-docs";
 import {
   createDocsModel,
-  DocsApp,
   findDocsPage,
   findOpenApiEndpoint,
+} from "@heyo-sh/heyo-docs/model";
+import { changelogGroupForPage } from "@heyo-sh/heyo-docs/navigation";
+import {
   openApiEndpointDataPath,
   openApiEndpointDetail,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
+} from "@heyo-sh/heyo-docs/openapi";
+import { docsSeoMeta } from "@heyo-sh/heyo-docs/seo/react-router";
+import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs/types";
+import { useDocsTheme } from "@heyo-sh/heyo-docs/theme/provider";
 import {
   Link,
   useLoaderData,
@@ -15,9 +20,9 @@ import {
   type MetaFunction,
 } from "react-router";
 import { forwardRef, type ComponentPropsWithoutRef } from "react";
+import { __HEYO_THEME_IDENTIFIER__ } from "@heyo-sh/heyo-docs/theme/__HEYO_THEME__";
 
 import { iconSet } from "../heyo-docs-icons";
-import { useTheme } from "../components/theme-provider";
 import { config } from "virtual:heyo-docs-config";
 import { pages } from "virtual:heyo-docs-content";
 import { openApiDocuments } from "virtual:heyo-docs-openapi";
@@ -80,59 +85,16 @@ export const meta: MetaFunction = ({ params }) => {
       { title: `Not found | ${config.title}` },
       { name: "robots", content: "noindex" },
     ];
-  const title = page?.seo.title ?? `${endpoint!.title} | ${config.title}`;
-  const description =
-    page?.seo.description ??
-    endpoint?.description ??
-    `${endpoint!.method.toUpperCase()} ${endpoint!.path} API endpoint.`;
-  const canonical =
-    page?.seo.canonical ??
-    (config.siteUrl ? `${config.siteUrl}${pathname}` : undefined);
-  return [
-    { title },
-    { name: "description", content: description },
-    { name: "robots", content: "index, follow" },
-    { property: "og:type", content: "article" },
-    { property: "og:site_name", content: config.title },
-    { property: "og:title", content: title },
-    { property: "og:description", content: description },
-    { name: "twitter:card", content: "summary" },
-    { name: "twitter:title", content: title },
-    { name: "twitter:description", content: description },
-    ...(canonical
-      ? [
-          { property: "og:url", content: canonical },
-          {
-            tagName: "link" as const,
-            rel: "canonical",
-            href: canonical,
-          },
-        ]
-      : []),
-    {
-      "script:ld+json": [
-        {
-          "@context": "https://schema.org",
-          "@type": "WebSite",
-          name: config.title,
-          description: config.description,
-          ...(config.siteUrl ? { url: config.siteUrl } : {}),
-        },
-        {
-          "@context": "https://schema.org",
-          "@type": "TechArticle",
-          headline: page?.title ?? endpoint!.title,
-          description,
-          ...(canonical ? { url: canonical } : {}),
-          isPartOf: {
-            "@type": "WebSite",
-            name: config.title,
-            ...(config.siteUrl ? { url: config.siteUrl } : {}),
-          },
-        },
-      ],
-    },
-  ];
+  return docsSeoMeta({
+    config,
+    pathname,
+    page,
+    endpoint,
+    navigation: model.navigation,
+    changelogGroup: page
+      ? changelogGroupForPage(config.groups, page, model.pages)
+      : undefined,
+  });
 };
 
 export default function DocsRoute() {
@@ -152,7 +114,7 @@ function DocsShell({
   currentOpenApiEndpoint?: OpenApiEndpoint;
   pathname: string;
 }) {
-  const { mounted, resolvedTheme, setTheme } = useTheme();
+  const { mounted, resolvedTheme, toggleTheme } = useDocsTheme();
 
   return (
     <DocsApp
@@ -164,12 +126,9 @@ function DocsShell({
       openApiRequestUrl="/heyo-docs-internal/openapi-request"
       pages={pages}
       pathname={pathname}
+      theme={__HEYO_THEME_IDENTIFIER__}
       isDark={mounted ? resolvedTheme === "dark" : undefined}
-      onThemeToggle={
-        mounted
-          ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
-          : undefined
-      }
+      onThemeToggle={mounted ? toggleTheme : undefined}
     />
   );
 }

package/templates/react-router/app/routes/home.tsx

@@ -1,4 +1,5 @@
-import { createDocsModel, navigationPages } from "@heyo-sh/heyo-docs";
+import { createDocsModel } from "@heyo-sh/heyo-docs/model";
+import { navigationPages } from "@heyo-sh/heyo-docs/navigation";
 import { redirect } from "react-router";
 
 import { config } from "virtual:heyo-docs-config";
@@ -14,6 +15,10 @@ export function loader() {
       status: 404,
     });
 
+  // `content/index.mdx` is a valid minimal starter. Redirecting `/` to `/`
+  // creates an infinite prerender redirect on Workers, so render DocsRoute in
+  // place when the first document owns the root path.
+  if (firstPage.slug === "/") return {};
   return redirect(firstPage.slug);
 }
 

package/templates/react-router/app/routes/llms-full.ts

@@ -1,4 +1,4 @@
-import { llmsFull } from "@heyo-sh/heyo-docs";
+import { llmsFull } from "@heyo-sh/heyo-docs/llm";
 import type { LoaderFunctionArgs } from "react-router";
 
 import config from "../../heyo-docs.config";

package/templates/react-router/app/routes/llms.ts

@@ -1,4 +1,4 @@
-import { llmsIndex } from "@heyo-sh/heyo-docs";
+import { llmsIndex } from "@heyo-sh/heyo-docs/llm";
 import type { LoaderFunctionArgs } from "react-router";
 
 import config from "../../heyo-docs.config";

package/templates/react-router/app/routes/markdown.ts

@@ -1,4 +1,7 @@
-import { markdownForPage, pathnameFromMarkdownPath } from "@heyo-sh/heyo-docs";
+import {
+  markdownForPage,
+  pathnameFromMarkdownPath,
+} from "@heyo-sh/heyo-docs/llm";
 import type { LoaderFunctionArgs } from "react-router";
 
 import { pages } from "virtual:heyo-docs-content/server";

package/templates/react-router/app/routes/openapi-request.ts

@@ -1,159 +1,26 @@
-import {
-  createDocsModel,
-  findOpenApiEndpoint,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
+import { createDocsModel } from "@heyo-sh/heyo-docs/model";
+import { handleOpenApiRequest } from "@heyo-sh/heyo-docs/openapi/request";
 import type { ActionFunctionArgs } from "react-router";
 
 import config from "../../heyo-docs.config";
 import { pages } from "virtual:heyo-docs-content";
 import { openApiDocuments } from "virtual:heyo-docs-openapi";
 
-interface OpenApiRequestPayload {
-  bearerToken: string;
-  body?: string;
-  endpointSlug: string;
-  parameters: Record<string, string>;
-  server: string;
+export function loader() {
+  return new Response("Method Not Allowed", {
+    status: 405,
+    headers: { Allow: "POST" },
+  });
 }
 
-/**
- * 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 action({ request }: ActionFunctionArgs) {
   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,
+  return handleOpenApiRequest(
+    request,
+    createDocsModel(config, pages, openApiDocuments).endpoints,
   );
-
-  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",
-    ),
-  );
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
 }

package/templates/react-router/app/routes/rss.ts

@@ -1,4 +1,4 @@
-import { rssXml } from "@heyo-sh/heyo-docs";
+import { rssXml } from "@heyo-sh/heyo-docs/rss";
 import type { LoaderFunctionArgs } from "react-router";
 
 import config from "../../heyo-docs.config";

package/templates/react-router/app/routes/sitemap.ts

@@ -1,4 +1,5 @@
-import { createDocsModel, sitemapXml } from "@heyo-sh/heyo-docs";
+import { createDocsModel } from "@heyo-sh/heyo-docs/model";
+import { sitemapPaths, sitemapXml } from "@heyo-sh/heyo-docs/seo";
 import type { Route } from "./+types/sitemap";
 
 import config from "../../heyo-docs.config";
@@ -8,11 +9,7 @@ import { openApiDocuments } from "virtual:heyo-docs-openapi";
 export function loader({ request }: Route.LoaderArgs) {
   const siteUrl = config.siteUrl ?? new URL(request.url).origin;
   const model = createDocsModel(config, pages, openApiDocuments);
-  return new Response(
-    sitemapXml(
-      siteUrl,
-      [...model.pages, ...model.endpoints].map((page) => page.slug),
-    ),
-    { headers: { "content-type": "application/xml; charset=utf-8" } },
-  );
+  return new Response(sitemapXml(siteUrl, sitemapPaths(model)), {
+    headers: { "content-type": "application/xml; charset=utf-8" },
+  });
 }

package/templates/react-router/app/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/react-router/content/index.mdx

@@ -0,0 +1,8 @@
+---
+title: "Welcome"
+description: "Get started with {{PROJECT_NAME}}."
+---
+
+# Welcome
+
+This documentation is ready for your content. Edit this page or add Markdown and MDX files in `content/`.

package/templates/react-router/heyo-docs.config.ts

@@ -1,56 +1,12 @@
-import { heyoDocs } from "@heyo-sh/heyo-docs";
+import { heyoDocs } from "@heyo-sh/heyo-docs/config";
 
 export default heyoDocs({
   title: "{{PROJECT_NAME}}",
   description: "Developer documentation",
-  content: "./content",
   theme: "{{THEME}}",
-  mode: "system",
-  groups: [
-    {
-      group: "Documentation",
-      icon: "globe",
-      sections: [
-        {
-          section: "Get Started",
-          icon: "lightbulb",
-          pages: ["quickstart", "configuration", "deploying"],
-        },
-        {
-          section: "Essentials",
-          icon: "book",
-          pages: [
-            "essentials/text-styling",
-            "essentials/code-blocks",
-            "essentials/callouts",
-            "essentials/tabs",
-            "essentials/lists",
-            "essentials/tables",
-          ],
-        },
-      ],
-    },
-    {
-      group: "OpenAPI",
-      icon: "code",
-      sections: [
-        {
-          pages: ["api-overview"],
-        },
-        {
-          schema: "./openapi.json",
-        },
-      ],
-    },
-    {
-      group: "Changelog",
-      description: "Mock release notes for the Heyo Docs demo.",
-      icon: "changelog",
-      type: "changelog",
-      updates: ["changelog"],
-    },
-  ],
   branding: { name: "{{PROJECT_NAME}}", logo: "/logo.svg" },
-  // Set this before deploying to publish canonical and absolute social URLs.
+  // Set this before deploying to publish canonical, sitemap, and social URLs.
   // siteUrl: "https://docs.example.com",
+  // Add analytics, consent, and support integrations here when you need them.
+  // integrations: { analytics: { ga4: { measurementId: "G-..." } } },
 });

package/templates/astro/content/api-overview.mdx

@@ -1,20 +0,0 @@
----
-title: API overview
-description: Learn how to authenticate and explore the API reference.
----
-
-# API overview
-
-The API reference is generated from `openapi.json`. Use the endpoint pages to
-enter parameters, send a request, and copy a cURL or JavaScript example.
-
-## Authentication
-
-The example API uses a Bearer token. Enter it once on any protected endpoint;
-Heyo Docs keeps it in this browser while you move between API pages.
-
-## Custom pages first
-
-This ordinary MDX page belongs to the OpenAPI group. Its section is configured
-before the generated endpoint sections, so it always appears at the top of the
-sidebar.

package/templates/astro/content/assets/local-architecture.svg

@@ -1,22 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="360" viewBox="0 0 960 360" fill="none">
-  <rect width="960" height="360" rx="24" fill="#F7F7F8"/>
-  <g fill="#FFFFFF" stroke="#D4D4D8" stroke-width="2">
-    <rect x="72" y="108" width="220" height="144" rx="18"/>
-    <rect x="370" y="108" width="220" height="144" rx="18"/>
-    <rect x="668" y="108" width="220" height="144" rx="18"/>
-  </g>
-  <g fill="#18181B" font-family="Arial, sans-serif" text-anchor="middle">
-    <text x="182" y="166" font-size="17" font-weight="700">Content</text>
-    <text x="182" y="194" font-size="14" fill="#71717A">MDX and assets</text>
-    <text x="480" y="166" font-size="17" font-weight="700">Build</text>
-    <text x="480" y="194" font-size="14" fill="#71717A">Vite bundles files</text>
-    <text x="778" y="166" font-size="17" font-weight="700">Documentation</text>
-    <text x="778" y="194" font-size="14" fill="#71717A">Static output</text>
-  </g>
-  <g stroke="#71717A" stroke-linecap="round" stroke-width="2">
-    <path d="M314 180h34"/>
-    <path d="m340 172 8 8-8 8"/>
-    <path d="M612 180h34"/>
-    <path d="m638 172 8 8-8 8"/>
-  </g>
-</svg>

package/templates/astro/content/assets/quick-reference.txt

@@ -1,5 +0,0 @@
-Heyo Docs quick reference
-
-- Put MDX pages and local assets in content.
-- Use a relative path to bundle an image or downloadable file.
-- Use /path for assets in public.

package/templates/astro/content/changelog.mdx

@@ -1,38 +0,0 @@
----
-title: Changelog
-description: Mock release notes for the Heyo Docs example.
----
-
-# Changelog
-
-<Update label="April 2026" tags={["New", "Documentation"]}>
-
-## Starter documentation
-
-New projects and runnable examples now include a structured Quickstart, basic
-configuration guide, deployment overview, and essential writing patterns.
-
-## Square API group
-
-The example navigation now keeps the pinned Square OpenAPI schema in its own
-group, making large-schema behaviour easy to inspect.
-
-</Update>
-
-<Update label="March 2026" tags={["Improved", "Developer experience"]}>
-
-## Clearer navigation
-
-External documentation links can display an icon, and sidebar groups now keep
-onboarding, API reference, and release notes separate.
-
-</Update>
-
-<Update label="February 2026" tags={["Fixed"]}>
-
-## More predictable previews
-
-Preview builds now validate configured routes before mock release notes are
-published.
-
-</Update>