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

package/templates/astro/content/openapi.json

@@ -0,0 +1,278 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Planet API",
+    "version": "1.0.0",
+    "description": "An example API used by the Heyo Docs React Router demo."
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com/v1",
+      "description": "Example production API"
+    }
+  ],
+  "security": [
+    {
+      "BearerAuth": []
+    }
+  ],
+  "paths": {
+    "/organizations/{organizationId}/planets": {
+      "parameters": [
+        {
+          "name": "organizationId",
+          "in": "path",
+          "required": true,
+          "description": "The organization that owns the planets.",
+          "schema": {
+            "type": "string",
+            "example": "org_123"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "listPlanets",
+        "summary": "List planets",
+        "description": "Returns the planets that belong to an organization.",
+        "tags": ["Planets"],
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Maximum number of records to return.",
+            "schema": {
+              "type": "integer",
+              "default": 20
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A page of planets.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/Planet"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createPlanet",
+        "summary": "Create a planet",
+        "description": "Creates a planet inside an organization.",
+        "tags": ["Planets"],
+        "requestBody": {
+          "required": true,
+          "description": "The planet to create.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PlanetInput"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "The newly created planet.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Planet"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/organizations/{organizationId}/planets/{planetId}": {
+      "parameters": [
+        {
+          "name": "organizationId",
+          "in": "path",
+          "required": true,
+          "description": "The organization that owns the planet.",
+          "schema": {
+            "type": "string",
+            "example": "org_123"
+          }
+        },
+        {
+          "name": "planetId",
+          "in": "path",
+          "required": true,
+          "description": "The planet identifier.",
+          "schema": {
+            "type": "string",
+            "example": "planet_earth"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "getPlanet",
+        "summary": "Get a planet",
+        "description": "Returns one planet by ID.",
+        "tags": ["Planets"],
+        "responses": {
+          "200": {
+            "description": "The requested planet.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Planet"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Planet not found."
+          }
+        }
+      },
+      "put": {
+        "operationId": "replacePlanet",
+        "summary": "Replace a planet",
+        "description": "Replaces all editable planet values.",
+        "tags": ["Planets"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PlanetInput"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated planet.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Planet"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "operationId": "updatePlanet",
+        "summary": "Update a planet",
+        "description": "Updates one or more planet fields.",
+        "tags": ["Planets"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PlanetPatch"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated planet.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Planet"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deletePlanet",
+        "summary": "Delete a planet",
+        "description": "Permanently removes a planet from an organization.",
+        "tags": ["Planets"],
+        "parameters": [
+          {
+            "name": "hardDelete",
+            "in": "query",
+            "description": "Also remove historical records.",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Planet deleted."
+          },
+          "404": {
+            "description": "Planet not found."
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "Planet": {
+        "type": "object",
+        "required": ["id", "name", "classification"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "example": "planet_earth"
+          },
+          "name": {
+            "type": "string",
+            "example": "Earth"
+          },
+          "classification": {
+            "type": "string",
+            "enum": ["terrestrial", "gas-giant", "ice-giant"]
+          }
+        }
+      },
+      "PlanetInput": {
+        "type": "object",
+        "required": ["name", "classification"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "example": "Mars"
+          },
+          "classification": {
+            "type": "string",
+            "enum": ["terrestrial", "gas-giant", "ice-giant"]
+          }
+        }
+      },
+      "PlanetPatch": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "example": "New Mars"
+          },
+          "classification": {
+            "type": "string",
+            "enum": ["terrestrial", "gas-giant", "ice-giant"]
+          }
+        }
+      }
+    }
+  }
+}

package/templates/astro/heyo-docs.config.ts

@@ -11,15 +11,6 @@ export default heyoDocs({
       group: "Documentation",
       icon: "globe",
       sections: [
-        {
-          pages: [
-            {
-              title: "Documentation",
-              src: "https://docs.heyo.sh/introduction",
-              icon: "book",
-            },
-          ],
-        },
         {
           section: "Get Started",
           icon: "lightbulb",
@@ -39,8 +30,27 @@ export default heyoDocs({
         },
       ],
     },
+    {
+      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}}" },
+  branding: { name: "{{PROJECT_NAME}}", logo: "/logo.svg" },
   // Set this before deploying to publish canonical and absolute social URLs.
   // siteUrl: "https://docs.example.com",
 });

package/templates/astro/src/components/docs-app.tsx

@@ -15,9 +15,9 @@ import {
   type MouseEvent,
 } from "react";
 
-import config from "../../heyo-docs.config";
 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";

package/templates/astro/src/layouts/docs-layout.astro

@@ -60,6 +60,7 @@ import {
   zammadChatScript,
 } from "@heyo-sh/heyo-docs/integrations/support/zammad";
 import "../styles/app.css";
+import "virtual:heyo-docs-theme.css";
 import { getThemeScript, THEME_STORAGE_KEY } from "../lib/theme";
 
 interface Props {

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

@@ -0,0 +1,20 @@
+import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
+import type { APIRoute } from "astro";
+
+import config from "../../../heyo-docs.config";
+import { pages as markdownPages } from "virtual:heyo-docs-content/server";
+
+export const prerender = false;
+
+export const POST: APIRoute = ({ request }) =>
+  createAiChatResponse(request, {
+    ai: config.ai,
+    markdownPages,
+    pages: markdownPages.map((page) => ({
+      description: page.description,
+      searchContent: page.raw,
+      slug: page.slug,
+      title: page.title,
+    })),
+    title: config.title,
+  });

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

@@ -0,0 +1,13 @@
+---
+import { navigationPages } from "@heyo-sh/heyo-docs";
+
+import { docsContext } from "../lib/docs";
+
+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);
+---

package/templates/astro/src/styles/app.css

@@ -1,8 +1,18 @@
 @import "@fontsource-variable/figtree";
-@import "@heyo-sh/heyo-docs/theme/{{THEME}}.css";
 
 :root {
   --heyo-docs-font-family: "Figtree Variable", sans-serif;
 }
 
-/* Add project-specific token overrides and theme styles below this import. */
+/* Add project-specific token overrides and theme styles here. */
+@media (min-width: 1024px) {
+  header > a[aria-label] > img[src="/logo.svg"] {
+    height: 32px;
+    max-height: none;
+    width: auto;
+  }
+}
+
+.dark header > a[aria-label] > img[src="/logo.svg"] {
+  filter: invert(1);
+}

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

@@ -3,6 +3,13 @@ declare module "virtual:heyo-docs-content" {
   export const pages: DocsPage[];
 }
 
+declare module "virtual:heyo-docs-config" {
+  import type { HeyoDocsConfig } from "@heyo-sh/heyo-docs";
+  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";
   export const pages: MarkdownPage[];

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

@@ -1,6 +1,9 @@
 import type { Metadata } from "next";
-import { notFound } from "next/navigation";
-import { openApiEndpointDetail } from "@heyo-sh/heyo-docs/node";
+import { notFound, redirect } from "next/navigation";
+import {
+  navigationPages,
+  openApiEndpointDetail,
+} from "@heyo-sh/heyo-docs/node";
 
 import { NextDocsApp } from "../components/docs-app";
 import { docsContext, docsModel, pathnameForSegments } from "../lib/docs";
@@ -14,9 +17,12 @@ interface PageProps {
 export const dynamic = "force-static";
 
 export async function generateStaticParams() {
-  return [...docsModel.pages, ...docsModel.endpoints].map(({ slug }) => ({
-    slug: slug === "/" ? [] : slug.slice(1).split("/"),
-  }));
+  return [
+    { slug: [] },
+    ...[...docsModel.pages, ...docsModel.endpoints].map(({ slug }) => ({
+      slug: slug.slice(1).split("/"),
+    })),
+  ];
 }
 
 export async function generateMetadata({
@@ -25,6 +31,11 @@ export async function generateMetadata({
   const { slug } = await params;
   const pathname = pathnameForSegments(slug);
   const context = docsContext(pathname);
+  if (pathname === "/")
+    return {
+      title: context.config.title,
+      robots: { index: false, follow: false },
+    };
   if (!context.page && !context.endpoint)
     return {
       title: `Not found | ${context.config.title}`,
@@ -36,6 +47,16 @@ export async function generateMetadata({
 export default async function DocsPage({ params }: PageProps) {
   const { slug } = await params;
   const pathname = pathnameForSegments(slug);
+  if (pathname === "/") {
+    const firstPage = docsModel.navigation
+      .flatMap((group) => navigationPages(group.sections))
+      .at(0);
+
+    if (!firstPage)
+      throw new Error("No local documentation page is configured.");
+
+    redirect(firstPage.slug);
+  }
   const context = docsContext(pathname);
   if (!context.page && !context.endpoint) notFound();
   const { structuredData } = docsSeo({ ...context, pathname });

package/templates/next/app/app.css

@@ -1,8 +1,18 @@
 @import "@fontsource-variable/figtree";
-@import "@heyo-sh/heyo-docs/theme/{{THEME}}.css";
 
 :root {
   --heyo-docs-font-family: "Figtree Variable", sans-serif;
 }
 
-/* Add project-specific token overrides and theme styles below this import. */
+/* Add project-specific token overrides and theme styles here. */
+@media (min-width: 1024px) {
+  header > a[aria-label] > img[src="/logo.svg"] {
+    height: 32px;
+    max-height: none;
+    width: auto;
+  }
+}
+
+.dark header > a[aria-label] > img[src="/logo.svg"] {
+  filter: invert(1);
+}

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

@@ -18,7 +18,6 @@ import {
 } from "react";
 
 import { docsConfig, openApiEndpoints, pages } from "../_heyo-docs/content";
-import config from "../../heyo-docs.config";
 import { iconSet } from "../heyo-docs-icons";
 import { useTheme } from "./theme-provider";
 
@@ -119,7 +118,7 @@ export function NextDocsApp({
   return (
     <NextNavigationContext.Provider value={navigate}>
       <DocsApp
-        config={{ ...docsConfig, navigation: config.navigation }}
+        config={docsConfig}
         iconSet={iconSet}
         isDark={mounted ? resolvedTheme === "dark" : undefined}
         link={NextDocsLink}

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

@@ -0,0 +1,15 @@
+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) {
+  return createAiChatResponse(request, {
+    ai: config.ai,
+    markdownPages,
+    pages: docsPages,
+    title: config.title,
+  });
+}

package/templates/next/app/layout.tsx

@@ -62,6 +62,7 @@ import {
 
 import config from "../heyo-docs.config";
 import "./app.css";
+import "./_heyo-docs/theme.css";
 import { ThemeProvider } from "./components/theme-provider";
 import { getThemeScript, THEME_STORAGE_KEY } from "./lib/theme";
 

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

@@ -0,0 +1,20 @@
+---
+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

@@ -0,0 +1,22 @@
+<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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,38 @@
+---
+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

@@ -64,6 +64,47 @@ 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 selected explicitly for the provider.
+
+<CodeBlock language="ts" title="heyo-docs.config.ts">
+  {`ai: {
+  chat: {
+    provider: "openai",
+    model: "gpt-5-mini",
+    auth: { type: "api-key", token: process.env.OPENAI_API_KEY! },
+    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`, `model`, and `auth` are required. API-key providers use
+`{ type: "api-key", token }`. GitHub Copilot and OpenAI Codex use
+`{ type: "oauth", getAccessToken }`; the resolver runs before each Pi request,
+so it can refresh a short-lived token. 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.