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

package/deployments/cloudflare/astro/package.json

@@ -1,7 +1,8 @@
 {
   "scripts": {
     "deploy": "wrangler deploy --config dist/server/wrangler.json",
-    "cf-typegen": "wrangler types --config dist/server/wrangler.json"
+    "cf-typegen": "wrangler types",
+    "typecheck": "bun run cf-typegen && astro check"
   },
   "dependencies": {
     "@astrojs/cloudflare": "14.2.6"

package/deployments/cloudflare/astro/src/env.d.ts

@@ -1,5 +1,8 @@
 declare namespace Cloudflare {
   interface Env {
-    OPENAI_API_KEY: string;
+    /** Preferred generic API-key binding; provider-specific auth stays in config. */
+    HEYO_DOCS_AI_API_KEY?: string;
+    /** @deprecated Use HEYO_DOCS_AI_API_KEY or config.ai.chat.auth. */
+    OPENAI_API_KEY?: string;
   }
 }

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

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

@@ -1,4 +1,3 @@
-import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
 import { getCloudflareContext } from "@opennextjs/cloudflare";
 
 import config from "../../../heyo-docs.config";
@@ -7,17 +6,20 @@ import { docsPages, markdownPages } from "../../_heyo-docs/server";
 export const runtime = "nodejs";
 
 export async function POST(request: Request) {
-  const { env } = getCloudflareContext();
-  const apiKey = env.OPENAI_API_KEY;
-  if (!apiKey)
+  if (!config.ai?.chat)
     return Response.json(
-      { error: "The OPENAI_API_KEY Worker secret is not configured." },
-      { status: 500 },
+      { error: "AI chat is not configured." },
+      { status: 404 },
     );
 
+  const { env } = getCloudflareContext();
+  const token = env.HEYO_DOCS_AI_API_KEY ?? env.OPENAI_API_KEY;
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
   return createAiChatResponse(request, {
     ai: config.ai,
-    auth: { type: "api-key", token: apiKey },
+    ...(config.ai?.chat.auth || !token
+      ? {}
+      : { auth: { type: "api-key" as const, token } }),
     markdownPages,
     pages: docsPages,
     title: config.title,

package/deployments/cloudflare/next/cloudflare-env.d.ts

@@ -1,4 +1,7 @@
 /** Cloudflare Worker secret configured with `wrangler secret put`. */
 interface CloudflareEnv {
-  OPENAI_API_KEY: string;
+  /** Preferred generic API-key binding; provider-specific auth stays in config. */
+  HEYO_DOCS_AI_API_KEY?: string;
+  /** @deprecated Use HEYO_DOCS_AI_API_KEY or config.ai.chat.auth. */
+  OPENAI_API_KEY?: string;
 }

package/deployments/cloudflare/react-router/app/cloudflare-env.d.ts

@@ -1,4 +1,7 @@
 /** Cloudflare Worker secret configured with `wrangler secret put`. */
 interface Env {
-  OPENAI_API_KEY: string;
+  /** Preferred generic API-key binding; provider-specific auth stays in config. */
+  HEYO_DOCS_AI_API_KEY?: string;
+  /** @deprecated Use HEYO_DOCS_AI_API_KEY or config.ai.chat.auth. */
+  OPENAI_API_KEY?: string;
 }

package/deployments/cloudflare/react-router/app/routes/ai-chat.ts

@@ -8,21 +8,22 @@ import { pages as markdownPages } from "virtual:heyo-docs-content/server";
 export async function action({ context, request }: ActionFunctionArgs) {
   if (request.method !== "POST")
     return new Response("Method Not Allowed", {
-      headers: { Allow: "POST" },
       status: 405,
+      headers: { Allow: "POST" },
     });
-
-  const apiKey = context.get(cloudflareContext).OPENAI_API_KEY;
-  if (!apiKey)
+  if (!config.ai?.chat)
     return Response.json(
-      { error: "The OPENAI_API_KEY Worker secret is not configured." },
-      { status: 500 },
+      { error: "AI chat is not configured." },
+      { status: 404 },
     );
-
+  const bindings = context.get(cloudflareContext);
+  const token = bindings.HEYO_DOCS_AI_API_KEY ?? bindings.OPENAI_API_KEY;
   const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
   return createAiChatResponse(request, {
     ai: config.ai,
-    auth: { type: "api-key", token: apiKey },
+    ...(config.ai?.chat.auth || !token
+      ? {}
+      : { auth: { type: "api-key" as const, token } }),
     markdownPages,
     pages,
     title: config.title,

package/deployments/cloudflare/react-router/package.json

@@ -5,7 +5,8 @@
   },
   "scripts": {
     "deploy": "wrangler deploy",
-    "cf-typegen": "wrangler types"
+    "cf-typegen": "wrangler types",
+    "typecheck": "bun run cf-typegen && react-router typegen && tsc -p tsconfig.json"
   },
   "devDependencies": {
     "@react-router/dev": "8.3.0",

package/deployments/vercel/astro/package.json

@@ -1,5 +1,6 @@
 {
   "scripts": {
+    "start": "vercel dev",
     "deploy": "vercel --prod"
   },
   "dependencies": {

package/dist/index.js

@@ -77,7 +77,10 @@ import {
 } from "node:fs/promises";
 import { dirname, join } from "node:path";
 function replacePlaceholders(source, values) {
-  return source.replace(/\{\{([A-Z0-9_]+)\}\}/g, (placeholder, key) => values[key] ?? placeholder);
+  return source.replace(/\{\{([A-Z0-9_]+)\}\}|__(HEYO_[A-Z0-9_]+)__/g, (placeholder, mustacheKey, tokenKey) => {
+    const key = mustacheKey ?? tokenKey;
+    return key ? values[key] ?? placeholder : placeholder;
+  });
 }
 function mergePackageJson(base, overlay) {
   const merged = { ...base };
@@ -96,13 +99,28 @@ async function copyTemplate(source, destination, placeholders) {
 }
 async function replacePlaceholdersAtPath(path, values) {
   if (!(await stat(path)).isDirectory()) {
-    const contents = await readFile(path, "utf8");
-    await writeFile(path, replacePlaceholders(contents, values));
+    const contents = await readFile(path);
+    if (!isTextFile(contents))
+      return;
+    const source = contents.toString("utf8");
+    if (!source.includes("{{") && !source.includes("__HEYO_"))
+      return;
+    await writeFile(path, replacePlaceholders(source, values));
     return;
   }
   const entries = await readdir(path, { withFileTypes: true });
   await Promise.all(entries.map((entry) => replacePlaceholdersAtPath(join(path, entry.name), values)));
 }
+function isTextFile(contents) {
+  if (contents.includes(0))
+    return false;
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(contents);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function writeJson(path, data) {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(data, null, 2)}
@@ -133,7 +151,9 @@ async function scaffoldProject(options) {
     PROJECT_NAME: projectName,
     HEYO_DOCS_VERSION: options.heyoDocsVersion ?? "latest",
     PACKAGE_MANAGER: packageManagerField(options.packageManager),
-    THEME: options.theme
+    THEME: options.theme,
+    HEYO_THEME: options.theme,
+    HEYO_THEME_IDENTIFIER: `${options.theme}Theme`
   };
   const templatePath = join2(packageRoot, "templates", options.template);
   const deploymentPath = join2(packageRoot, "deployments", options.deployment, options.template);

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,eAAO,MAAM,uCAAuC,+IAC0F,CAAC;AAE/I,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,YAAY,CAAC,GACtD,IAAI,CAGN;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAgDlC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,eAAO,MAAM,uCAAuC,+IAC0F,CAAC;AAE/I,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,YAAY,CAAC,GACtD,IAAI,CAGN;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAkDlC"}

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAWA,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,CAAC,CASH;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAOf;AAoBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE1D;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAWA,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAYR;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,CAAC,CASH;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAOf;AAwCD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE1D;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyo-sh/create-heyo-docs",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Create a standalone Heyo Docs documentation project.",
   "homepage": "https://heyo.sh",
   "repository": {

package/templates/astro/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/astro/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/src/components/docs-app.tsx

@@ -1,62 +1,21 @@
-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 { 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 { DEFAULT_THEME_STORAGE_KEY } from "@heyo-sh/heyo-docs/theme/script";
+import { ThemeProvider, 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 { iconSet } from "../heyo-docs-icons";
-import { THEME_STORAGE_KEY } from "../lib/theme";
 import { config } from "virtual:heyo-docs-config";
 import { openApiEndpoints } from "virtual:heyo-docs-openapi/index";
 import { pages } from "virtual:heyo-docs-content";
-import { ThemeProvider, useTheme } from "./theme-provider";
 
-type Navigate = (href: string) => void;
-
-const AstroNavigationContext = createContext<Navigate | undefined>(undefined);
-
-const AstroLink = forwardRef<HTMLAnchorElement, ComponentPropsWithoutRef<"a">>(
-  function AstroLink({ href, onClick, target, ...props }, ref) {
-    const navigate = useContext(AstroNavigationContext);
-
-    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}
-      />
-    );
+// Astro uses ordinary document navigation for docs links. It preserves static
+// page HTML and metadata instead of maintaining a second router in React.
+const AstroLink = forwardRef<HTMLAnchorElement, DocsLinkProps>(
+  function AstroLink(props, ref) {
+    return <a {...props} ref={ref} />;
   },
 );
 
@@ -68,7 +27,10 @@ export function AstroDocsApp({
   pathname: string;
 }) {
   return (
-    <ThemeProvider defaultTheme={config.mode} storageKey={THEME_STORAGE_KEY}>
+    <ThemeProvider
+      defaultTheme={config.mode}
+      storageKey={DEFAULT_THEME_STORAGE_KEY}
+    >
       <DocsShell
         currentOpenApiEndpoint={currentOpenApiEndpoint}
         pathname={pathname}
@@ -77,10 +39,6 @@ export function AstroDocsApp({
   );
 }
 
-/**
- * Content is imported in this island instead of crossing Astro's serialisation
- * boundary. MDX pages are React components and must stay module references.
- */
 function DocsShell({
   currentOpenApiEndpoint,
   pathname,
@@ -88,78 +46,20 @@ function DocsShell({
   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} | ${config.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 (
-    <AstroNavigationContext.Provider value={navigate}>
-      <DocsApp
-        config={config}
-        iconSet={iconSet}
-        isDark={mounted ? resolvedTheme === "dark" : undefined}
-        link={AstroLink}
-        onThemeToggle={
-          mounted
-            ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
-            : undefined
-        }
-        currentOpenApiEndpoint={activeOpenApiEndpoint}
-        openApiEndpoints={openApiEndpoints}
-        openApiRequestUrl="/heyo-docs-internal/openapi-request"
-        pages={pages}
-        pathname={activePathname}
-      />
-    </AstroNavigationContext.Provider>
+    <DocsApp
+      config={config}
+      currentOpenApiEndpoint={currentOpenApiEndpoint}
+      iconSet={iconSet}
+      isDark={mounted ? resolvedTheme === "dark" : undefined}
+      link={AstroLink}
+      onThemeToggle={mounted ? toggleTheme : undefined}
+      openApiEndpoints={openApiEndpoints}
+      openApiRequestUrl="/heyo-docs-internal/openapi-request"
+      pages={pages}
+      pathname={pathname}
+      theme={__HEYO_THEME_IDENTIFIER__}
+    />
   );
 }

package/templates/astro/src/heyo-docs-icons.tsx

@@ -24,13 +24,14 @@ import {
   RiInformationLine,
   RiLightbulbLine,
   RiLoginBoxLine,
+  RiMenuLine,
   RiMoonLine,
   RiNewsLine,
   RiSearchLine,
   RiStarLine,
   RiSunLine,
 } from "@remixicon/react";
-import type { IconSet } from "@heyo-sh/heyo-docs";
+import type { IconSet } from "@heyo-sh/heyo-docs/types";
 
 /**
  * This mapping is intentionally local to the generated application. Replace
@@ -51,6 +52,7 @@ const remixIconSet = {
   arrowRight: RiArrowRightLine,
   close: RiCloseLine,
   cornerDownLeft: RiCornerDownLeftLine,
+  menu: RiMenuLine,
   search: RiSearchLine,
   sun: RiSunLine,
   moon: RiMoonLine,