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

package/templates/astro/src/lib/theme.ts

@@ -1,74 +0,0 @@
-export type Theme = "dark" | "light" | "system";
-export type ResolvedTheme = Exclude<Theme, "system">;
-
-export const DEFAULT_THEME: Theme = "system";
-export const THEME_STORAGE_KEY = "heyo-docs-theme";
-
-const themeValues = new Set<Theme>(["light", "dark", "system"]);
-
-export function isTheme(value: string | null): value is Theme {
-  return value !== null && themeValues.has(value as Theme);
-}
-
-export function getStoredTheme(
-  storageKey: string,
-  fallbackTheme: Theme,
-): Theme {
-  if (typeof window === "undefined") return fallbackTheme;
-
-  try {
-    const storedTheme = window.localStorage.getItem(storageKey);
-    return isTheme(storedTheme) ? storedTheme : fallbackTheme;
-  } catch {
-    return fallbackTheme;
-  }
-}
-
-export function getSystemTheme(): ResolvedTheme {
-  return window.matchMedia("(prefers-color-scheme: dark)").matches
-    ? "dark"
-    : "light";
-}
-
-export function resolveTheme(theme: Theme): ResolvedTheme {
-  return theme === "system" ? getSystemTheme() : theme;
-}
-
-export function applyTheme(theme: Theme): ResolvedTheme {
-  const resolvedTheme = resolveTheme(theme);
-  const root = window.document.documentElement;
-
-  root.classList.remove("light", "dark");
-  root.classList.add(resolvedTheme);
-  root.style.colorScheme = resolvedTheme;
-
-  return resolvedTheme;
-}
-
-export function getThemeScript(storageKey: string, defaultTheme: Theme) {
-  return `(() => {
-  const storageKey = ${JSON.stringify(storageKey)};
-  const fallbackTheme = ${JSON.stringify(defaultTheme)};
-  const isTheme = (value) => value === "light" || value === "dark" || value === "system";
-
-  const storedTheme = (() => {
-    try {
-      const value = window.localStorage.getItem(storageKey);
-      return isTheme(value) ? value : fallbackTheme;
-    } catch {
-      return fallbackTheme;
-    }
-  })();
-
-  const resolvedTheme = storedTheme === "system"
-    ? window.matchMedia("(prefers-color-scheme: dark)").matches
-      ? "dark"
-      : "light"
-    : storedTheme;
-
-  const root = document.documentElement;
-  root.classList.remove("light", "dark");
-  root.classList.add(resolvedTheme);
-  root.style.colorScheme = resolvedTheme;
-})();`;
-}

package/templates/next/app/components/theme-provider.tsx

@@ -1,93 +0,0 @@
-"use client";
-
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useState,
-  type ReactNode,
-} from "react";
-
-import {
-  applyTheme,
-  DEFAULT_THEME,
-  getStoredTheme,
-  type ResolvedTheme,
-  THEME_STORAGE_KEY,
-  type Theme,
-} from "../lib/theme";
-
-type ThemeProviderState = {
-  theme: Theme;
-  resolvedTheme: ResolvedTheme;
-  mounted: boolean;
-  setTheme: (theme: Theme) => void;
-};
-
-const ThemeProviderContext = createContext<ThemeProviderState | undefined>(
-  undefined,
-);
-
-export function ThemeProvider({
-  children,
-  defaultTheme = DEFAULT_THEME,
-  storageKey = THEME_STORAGE_KEY,
-}: {
-  children: ReactNode;
-  defaultTheme?: Theme;
-  storageKey?: string;
-}) {
-  const [theme, setThemeState] = useState<Theme>(defaultTheme);
-  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(
-    defaultTheme === "system" ? "light" : defaultTheme,
-  );
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    const syncTheme = () => {
-      const nextTheme = getStoredTheme(storageKey, defaultTheme);
-      setThemeState(nextTheme);
-      setResolvedTheme(applyTheme(nextTheme));
-    };
-    syncTheme();
-    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
-    const onSystemThemeChange = () => syncTheme();
-    const onStorage = (event: StorageEvent) => {
-      if (event.key === null || event.key === storageKey) syncTheme();
-    };
-    mediaQuery.addEventListener("change", onSystemThemeChange);
-    window.addEventListener("storage", onStorage);
-    setMounted(true);
-    return () => {
-      mediaQuery.removeEventListener("change", onSystemThemeChange);
-      window.removeEventListener("storage", onStorage);
-    };
-  }, [defaultTheme, storageKey]);
-
-  return (
-    <ThemeProviderContext.Provider
-      value={{
-        theme,
-        resolvedTheme,
-        mounted,
-        setTheme: (nextTheme) => {
-          try {
-            window.localStorage.setItem(storageKey, nextTheme);
-          } catch {
-            // The requested preference still applies when storage is unavailable.
-          }
-          setThemeState(nextTheme);
-          setResolvedTheme(applyTheme(nextTheme));
-        },
-      }}
-    >
-      {children}
-    </ThemeProviderContext.Provider>
-  );
-}
-
-export function useTheme() {
-  const context = useContext(ThemeProviderContext);
-  if (!context) throw new Error("useTheme must be used within a ThemeProvider");
-  return context;
-}

package/templates/next/app/lib/seo.ts

@@ -1,189 +0,0 @@
-import type { Metadata } from "next";
-import {
-  type ChangelogGroupConfig,
-  type DocsPage,
-  type HeyoDocsConfig,
-  type NavigationGroup,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
-import {
-  navigationGroupContainsPath,
-  navigationPages,
-  navigationSectionPathForPath,
-} from "@heyo-sh/heyo-docs/node";
-
-interface DocsSeoInput {
-  config: HeyoDocsConfig;
-  pathname: string;
-  page?: DocsPage;
-  endpoint?: OpenApiEndpoint;
-  changelogGroup?: ChangelogGroupConfig;
-  navigation: NavigationGroup[];
-}
-
-function canonicalFor({ config, pathname, page }: DocsSeoInput) {
-  return (
-    page?.seo.canonical ??
-    (config.siteUrl ? `${config.siteUrl}${pathname}` : undefined)
-  );
-}
-
-function website(config: HeyoDocsConfig) {
-  return {
-    "@type": "WebSite",
-    name: config.title,
-    ...(config.siteUrl ? { url: config.siteUrl } : {}),
-  };
-}
-
-function breadcrumbItems({
-  changelogGroup,
-  navigation,
-  pathname,
-  title,
-}: Pick<DocsSeoInput, "changelogGroup" | "navigation" | "pathname"> & {
-  title: string;
-}) {
-  if (changelogGroup) return [{ label: changelogGroup.group, href: pathname }];
-  const group = navigation.find((candidate) =>
-    navigationGroupContainsPath(candidate, pathname),
-  );
-  const sections = group
-    ? navigationSectionPathForPath(group.sections, pathname)
-    : undefined;
-  if (!group) return [{ label: title, href: pathname }];
-  return [
-    { label: group.group, href: navigationPages(group.sections)[0]?.slug },
-    ...(sections ?? []).map((section) => ({
-      label: section.section,
-      href: navigationPages([section])[0]?.slug,
-    })),
-    { label: title, href: pathname },
-  ];
-}
-
-function absoluteUrl(siteUrl: string | undefined, href: string | undefined) {
-  if (!siteUrl || !href) return undefined;
-  return /^https?:\/\//.test(href)
-    ? href
-    : new URL(href, `${siteUrl}/`).toString();
-}
-
-/** Next Metadata plus JSON-LD for MDX, changelog and generated API pages. */
-export function docsSeo(input: DocsSeoInput): {
-  metadata: Metadata;
-  structuredData: unknown[];
-} {
-  const { changelogGroup, config, endpoint, navigation, page, pathname } =
-    input;
-  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 = canonicalFor(input);
-  const pageType = endpoint
-    ? {
-        "@context": "https://schema.org",
-        "@type": "APIReference",
-        headline: title,
-        description,
-        ...(canonical ? { url: canonical } : {}),
-        isPartOf: website(config),
-        mainEntity: {
-          "@type": "EntryPoint",
-          name:
-            endpoint.operationId ??
-            `${endpoint.method.toUpperCase()} ${endpoint.path}`,
-          httpMethod: endpoint.method.toUpperCase(),
-          urlTemplate: endpoint.servers[0]
-            ? `${endpoint.servers[0].replace(/\/$/, "")}${endpoint.path}`
-            : endpoint.path,
-          ...(endpoint.requestBody?.contentType
-            ? { encodingType: endpoint.requestBody.contentType }
-            : {}),
-          ...(endpoint.responses[0]?.contentType
-            ? { contentType: endpoint.responses[0].contentType }
-            : {}),
-        },
-      }
-    : changelogGroup
-      ? {
-          "@context": "https://schema.org",
-          "@type": "CollectionPage",
-          headline: title,
-          description,
-          ...(canonical ? { url: canonical } : {}),
-          isPartOf: website(config),
-          ...(page?.changelogUpdates?.length
-            ? {
-                hasPart: page.changelogUpdates.map((update) => ({
-                  "@type": "TechArticle",
-                  headline: update.label,
-                  ...(update.tags.length
-                    ? { keywords: update.tags.join(", ") }
-                    : {}),
-                  ...(canonical ? { url: `${canonical}#${update.id}` } : {}),
-                })),
-              }
-            : {}),
-        }
-      : {
-          "@context": "https://schema.org",
-          "@type": "TechArticle",
-          headline: title,
-          description,
-          ...(canonical ? { url: canonical } : {}),
-          isPartOf: website(config),
-        };
-  const crumbs = breadcrumbItems({
-    changelogGroup,
-    navigation,
-    pathname,
-    title: page?.title ?? endpoint!.title,
-  });
-  const structuredData = [
-    pageType,
-    {
-      "@context": "https://schema.org",
-      "@type": "BreadcrumbList",
-      itemListElement: [
-        { label: config.title, href: config.siteUrl },
-        ...crumbs,
-      ].map((item, index, items) => ({
-        "@type": "ListItem",
-        position: index + 1,
-        name: item.label,
-        ...((
-          index === items.length - 1
-            ? canonical
-            : absoluteUrl(config.siteUrl, item.href)
-        )
-          ? {
-              item:
-                index === items.length - 1
-                  ? canonical
-                  : absoluteUrl(config.siteUrl, item.href),
-            }
-          : {}),
-      })),
-    },
-  ];
-  return {
-    metadata: {
-      title,
-      description,
-      robots: { index: true, follow: true },
-      alternates: canonical ? { canonical } : undefined,
-      openGraph: {
-        type: "article",
-        siteName: config.title,
-        title,
-        description,
-        ...(canonical ? { url: canonical } : {}),
-      },
-      twitter: { card: "summary", title, description },
-    },
-    structuredData,
-  };
-}

package/templates/next/app/lib/theme.ts

@@ -1,61 +0,0 @@
-export type Theme = "dark" | "light" | "system";
-export type ResolvedTheme = Exclude<Theme, "system">;
-
-export const DEFAULT_THEME: Theme = "system";
-export const THEME_STORAGE_KEY = "heyo-docs-theme";
-
-const themeValues = new Set<Theme>(["light", "dark", "system"]);
-
-export function isTheme(value: string | null): value is Theme {
-  return value !== null && themeValues.has(value as Theme);
-}
-
-export function getStoredTheme(
-  storageKey: string,
-  fallbackTheme: Theme,
-): Theme {
-  if (typeof window === "undefined") return fallbackTheme;
-  try {
-    const storedTheme = window.localStorage.getItem(storageKey);
-    return isTheme(storedTheme) ? storedTheme : fallbackTheme;
-  } catch {
-    return fallbackTheme;
-  }
-}
-
-export function applyTheme(theme: Theme): ResolvedTheme {
-  const resolvedTheme =
-    theme === "system"
-      ? window.matchMedia("(prefers-color-scheme: dark)").matches
-        ? "dark"
-        : "light"
-      : theme;
-  const root = window.document.documentElement;
-  root.classList.remove("light", "dark");
-  root.classList.add(resolvedTheme);
-  root.style.colorScheme = resolvedTheme;
-  return resolvedTheme;
-}
-
-export function getThemeScript(storageKey: string, defaultTheme: Theme) {
-  return `(() => {
-  const storageKey = ${JSON.stringify(storageKey)};
-  const fallbackTheme = ${JSON.stringify(defaultTheme)};
-  const isTheme = (value) => value === "light" || value === "dark" || value === "system";
-  const storedTheme = (() => {
-    try {
-      const value = window.localStorage.getItem(storageKey);
-      return isTheme(value) ? value : fallbackTheme;
-    } catch {
-      return fallbackTheme;
-    }
-  })();
-  const resolvedTheme = storedTheme === "system"
-    ? window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
-    : storedTheme;
-  const root = document.documentElement;
-  root.classList.remove("light", "dark");
-  root.classList.add(resolvedTheme);
-  root.style.colorScheme = resolvedTheme;
-})();`;
-}

package/templates/next/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/next/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/next/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/next/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>

package/templates/next/content/configuration.mdx

@@ -1,117 +0,0 @@
----
-title: Basic Configuration
-description: Set the identity, content source, and sidebar structure for a Heyo Docs site.
----
-
-# Basic Configuration
-
-`heyo-docs.config.ts` is the single source of truth for a Heyo Docs site.
-The framework integration and the documentation UI read the same validated
-object, so a change to navigation or metadata does not need to be repeated in
-multiple places.
-
-## Start with the site model
-
-The generated project already includes a working configuration. Update the
-identity fields first, then point `content` at the directory that contains
-your MDX files.
-
-<CodeBlock language="ts" title="heyo-docs.config.ts" showLineNumbers>
-  {`import { heyoDocs } from "@heyo-sh/heyo-docs";
-
-export default heyoDocs({
-  title: "{{PROJECT_NAME}}",
-  description: "Guides and reference for {{PROJECT_NAME}}.",
-  content: "./content",
-  theme: "grain",
-  mode: "system",
-  branding: { name: "{{PROJECT_NAME}}" },
-});`}
-</CodeBlock>
-
-Set `siteUrl` to the final public origin before publishing. It is used for
-canonical URLs, social metadata, the sitemap, RSS, and AI-facing discovery
-files.
-
-## Organize the sidebar
-
-Use `groups` to define the order readers see. A group contains named sections
-and their MDX page references; a reference is relative to `content` and does
-not include the `.mdx` extension.
-
-<CodeBlock language="ts" title="heyo-docs.config.ts">
-  {`groups: [
-  {
-    group: "Documentation",
-    icon: "globe",
-    sections: [
-      {
-        section: "Get Started",
-        icon: "lightbulb",
-        pages: ["quickstart", "configuration"],
-      },
-      {
-        section: "Essentials",
-        icon: "book",
-        pages: ["essentials/text-styling", "essentials/code-blocks"],
-      },
-    ],
-  },
-],`}
-</CodeBlock>
-
-The order is meaningful: it controls the sidebar and the previous/next links at
-the end of each article. Use a page object with `title` and `src` when a
-sidebar entry should point to a page outside the local documentation.
-
-## AI chat
-
-Add `ai.chat` to enable a documentation-aware chat through [Pi](https://github.com/badlogic/pi-mono).
-Use any provider identifier bundled with the installed Pi version, such as
-`openai`, `anthropic`, `google`, `openrouter`, or `xai`. Authentication stays
-server-only and is supplied by the route that handles the chat request.
-
-<CodeBlock language="ts" title="heyo-docs.config.ts">
-  {`ai: {
-  chat: {
-    provider: "openai",
-    model: "gpt-5-mini",
-    variant: "right", // "center" shows the compact prompt first
-    icon: "chat",
-    text: "AI Chat",
-    name: "Docs Assistant", // name shown in the drawer and message labels
-    placeholder: "Ask AI about the docs", // used in the compact prompt and drawer
-  },
-},`}
-</CodeBlock>
-
-`provider` and `model` are required. Keep the credential out of this
-configuration and pass it as `auth` to `createAiChatResponse` in the server
-route. Cloudflare routes obtain the key from the Worker `env` binding; Node.js
-routes can read their server environment there. GitHub Copilot and OpenAI Codex
-use `auth: { type: "oauth", getAccessToken }`; Amazon Bedrock uses either
-`{ type: "aws", region?, profile? }` and the AWS credential chain, or
-`{ type: "bedrock-bearer", token, region? }`. The model must be an actual model
-identifier, not the provider name. Amazon Bedrock requires a Node.js chat
-endpoint. `variant` defaults to `right`. `name`
-defaults to `AI`; it is used for the drawer title and the assistant's message
-label. `placeholder` defaults to
-`Ask AI about the docs` and is shared by the compact prompt and drawer input.
-The drawer stays open while
-readers navigate between documentation pages and does not block the rest of the
-page.
-
-Its chrome follows the selected documentation theme. For example, `grain` uses
-a full-height right panel with a left border, while the other themes keep a
-floating panel treatment.
-
-## Verify the result
-
-Run the project's typecheck and build commands after changing configuration.
-They resolve each configured MDX page and report missing paths or malformed
-navigation before the site is deployed.
-
-<Callout type="info" title="Keep page metadata close to the page">
-  Put a page's <code>title</code> and <code>description</code> in its MDX
-  frontmatter. Keep shared site settings in <code>heyo-docs.config.ts</code>.
-</Callout>

package/templates/next/content/deploying.mdx

@@ -1,70 +0,0 @@
----
-title: Deploying
-description: Build and publish your Heyo Docs site with the deployment target chosen during setup.
----
-
-# Deploying
-
-A Heyo Docs site is built as part of the framework application. The creator asks
-for a deployment target when the project is created and adds the corresponding
-configuration, so the same MDX content, navigation, search, and metadata are
-used locally and in production.
-
-## Choose the target during setup
-
-Select Vercel or Cloudflare when running the creator if you already know where
-the site will live. The generated project includes the adapter and deployment
-configuration required by that platform. You can also choose to configure
-deployment later and keep the starter focused on local development.
-
-## Build before publishing
-
-Run the production build on your machine before creating a deployment. It
-resolves every configured page, validates the navigation tree, and generates
-the sitemap, RSS feed, robots file, and AI-facing documentation endpoints.
-
-<CodeBlock language="bash" title="Terminal">
-  {"bun run build"}
-</CodeBlock>
-
-Use the equivalent `npm run build`, `pnpm build`, or `yarn build` command
-when the project uses a different package manager.
-
-## Cloudflare secrets
-
-For AI chat, save the provider key as a Worker secret:
-
-<CodeBlock language="bash" title="Terminal">
-  {"bunx wrangler secret put OPENAI_API_KEY"}
-</CodeBlock>
-
-Keep the credential out of `heyo-docs.config.ts`. The Cloudflare overlay reads
-the native Worker `env.OPENAI_API_KEY` binding in the AI route, after the
-request reaches the Worker. It is never part of the documentation build or the
-browser bundle.
-
-<Callout type="tip" title="Set the canonical URL">
-  Add the final public origin as <code>siteUrl</code> in
-  <code>heyo-docs.config.ts</code> before the first production release. It keeps
-  canonical links, social metadata, and generated discovery files consistent.
-</Callout>
-
-## Publish the project
-
-For a generated Vercel or Cloudflare project, connect the repository in the
-provider dashboard or run the deployment script included by the selected setup.
-The provider builds the application with the same command you verified locally.
-
-<Steps>
-  <Step title="Push the documentation source">
-    Commit the MDX content and <code>heyo-docs.config.ts</code> together so the
-    deployed navigation matches the reviewed pages.
-  </Step>
-  <Step title="Create a preview">
-    Review the provider's preview URL for layout, links, search, and metadata.
-  </Step>
-  <Step title="Promote the production build">
-    Publish once the preview is correct and the configured <code>siteUrl</code>
-    matches the public domain.
-  </Step>
-</Steps>