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

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

package/templates/astro/content/essentials/callouts.mdx

@@ -1,34 +0,0 @@
----
-title: Callouts
-description: Draw attention to a tip, warning, prerequisite, or result.
----
-
-# Callouts
-
-Use a callout when a reader should not miss a detail.
-
-## Add a tip
-
-<Callout type="tip" title="Keep examples focused">
-  Show one idea at a time so readers can apply it quickly.
-</Callout>
-
-## Choose a type
-
-| Type                  | Use it for             |
-| --------------------- | ---------------------- |
-| `info` or `note`      | Helpful context        |
-| `tip`                 | A recommended approach |
-| `check`               | A successful result    |
-| `warning` or `danger` | A real consequence     |
-
-<Callout type="warning" title="Preview before publishing">
-  Run the production build after changing navigation or MDX.
-</Callout>
-
-## Keep it short
-
-<Callout type="info" title="Configuration and content work together">
-  Navigation belongs in <code>heyo-docs.config.ts</code>. Titles and
-  descriptions belong in page frontmatter.
-</Callout>

package/templates/astro/content/essentials/code-blocks.mdx

@@ -1,43 +0,0 @@
----
-title: Code Blocks
-description: Add clear, copyable commands and configuration examples.
----
-
-# Code Blocks
-
-Show one task per example. Add a language so the code is easy to read.
-
-## Add a command
-
-```bash
-bun run dev
-bun run build
-```
-
-## Add a file name
-
-Use `CodeBlock` when the file name helps explain where the code belongs.
-
-<CodeBlock language="ts" title="heyo-docs.config.ts" showLineNumbers>
-  {`export default heyoDocs({
-  title: "Orbit Docs",
-  content: "content",
-  theme: "grain",
-});`}
-</CodeBlock>
-
-## Show alternatives
-
-Use `CodeBlockGroup` for equivalent commands, such as package managers.
-
-<CodeBlockGroup defaultValue="bun" variant="line">
-  <CodeBlock language="bash" title="bun">
-    {"bun add @heyo-sh/heyo-docs"}
-  </CodeBlock>
-  <CodeBlock language="bash" title="npm">
-    {"npm install @heyo-sh/heyo-docs"}
-  </CodeBlock>
-  <CodeBlock language="bash" title="pnpm">
-    {"pnpm add @heyo-sh/heyo-docs"}
-  </CodeBlock>
-</CodeBlockGroup>

package/templates/astro/content/essentials/lists.mdx

@@ -1,36 +0,0 @@
----
-title: Lists
-description: Use lists to make choices and short steps easy to scan.
----
-
-# Lists
-
-Use a list when readers need to scan choices or follow a short sequence.
-
-## Add a bullet list
-
-Use bullets when the order does not matter.
-
-- Keep MDX pages in the `content` directory.
-- Add important routes to `heyo-docs.config.ts`.
-- Build the project before publishing.
-
-## Add numbered steps
-
-Use numbers when the order matters.
-
-1. Create an MDX file.
-2. Add its path to a sidebar section.
-3. Start the development server.
-4. Review the rendered route.
-
-## Add one level when needed
-
-Use a nested list only for a direct relationship.
-
-- Prepare the release:
-  - Review the changed pages.
-  - Confirm navigation order.
-  - Run the production build.
-
-Use `Steps` when each step needs a command or more explanation.

package/templates/astro/content/essentials/tables.mdx

@@ -1,30 +0,0 @@
----
-title: Tables
-description: Compare a small set of options with a simple Markdown table.
----
-
-# Tables
-
-Use a table to compare the same details across a small number of options.
-
-## Add a table
-
-| Setting   | Purpose                                | Example                      |
-| --------- | -------------------------------------- | ---------------------------- |
-| `content` | Directory containing MDX source files. | `"content"`                  |
-| `theme`   | Built-in documentation theme.          | `"grain"`                    |
-| `mode`    | Initial color preference.              | `"system"`                   |
-| `siteUrl` | Canonical public site origin.          | `"https://docs.example.com"` |
-
-## Keep it readable
-
-Use short headings and short cells. Put long explanations in a section below
-the table.
-
-| Use a table for        | Use a section for      |
-| ---------------------- | ---------------------- |
-| Compact comparisons    | A multi-step procedure |
-| Option defaults        | A detailed explanation |
-| Short reference values | A large code example   |
-
-Use a numbered list when readers must act in a specific order.

package/templates/astro/content/essentials/tabs.mdx

@@ -1,40 +0,0 @@
----
-title: Tabs
-description: Let readers switch between equivalent commands or platforms.
----
-
-# Tabs
-
-Use tabs for equivalent ways to complete the same task. Keep their labels
-short.
-
-## Add tabs
-
-<Tabs defaultValue="typescript" variant="line">
-  <Tab title="JavaScript" value="javascript">
-    Import the package from your JavaScript entry point.
-  </Tab>
-  <Tab title="TypeScript" value="typescript">
-    Import the package with full type information and keep configuration typed.
-  </Tab>
-</Tabs>
-
-## Compare platforms
-
-Each tab should answer the same question for a different platform.
-
-<Tabs defaultValue="vercel" variant="line">
-  <Tab title="Vercel" value="vercel">
-    Connect the repository and let Vercel detect the framework.
-  </Tab>
-  <Tab title="Cloudflare" value="cloudflare">
-    Deploy the generated static site when your team already uses Cloudflare.
-  </Tab>
-  <Tab title="Static host" value="static">
-    Upload the build output to any host that serves static files.
-  </Tab>
-</Tabs>
-
-<Callout type="tip" title="Use tabs sparingly">
-  Use headings or <code>Steps</code> for information that every reader needs.
-</Callout>

package/templates/astro/content/essentials/text-styling.mdx

@@ -1,43 +0,0 @@
----
-title: Text Styling
-description: Use simple Markdown for headings, emphasis, links, and quotes.
----
-
-# Text Styling
-
-Use regular Markdown for most documentation. Keep the text short and let
-headings show readers where to look next.
-
-## Add headings
-
-Use `##` for a main section and `###` only for a useful subsection.
-
-```md
-## Configure navigation
-
-Add pages in the order readers should follow.
-
-### Add an external resource
-
-Link to a resource outside your documentation.
-```
-
-## Highlight important text
-
-Use **bold** for an important choice and inline `code` for values readers need
-to copy.
-
-```md
-Set `content: "content"` in `heyo-docs.config.ts`.
-
-Run `bun run build` before you publish.
-```
-
-## Write useful links
-
-Use the destination as the link text. It is easier to scan than a raw URL.
-
-Read the [Quickstart](/quickstart) before changing
-[site configuration](/configuration).
-
-> Keep one idea in each short paragraph.

package/templates/astro/content/getting-started.mdx

@@ -1,16 +0,0 @@
----
-title: Getting started
-description: Run your new documentation site locally.
----
-
-# Getting started
-
-Install dependencies with your chosen package manager and start the development server.
-
-## Create a page
-
-Create `content/guides/deploying.mdx` to get the `/guides/deploying` route. Its frontmatter controls its title and description.
-
-## Configure the documentation
-
-Use `heyo-docs.config.ts` to change the title, colors, tabs, sidebar groups, footer links and selected theme without regenerating your project. Add pages or directories to a section's `pages` list to control the sidebar order.

package/templates/astro/content/mdx-components.mdx

@@ -1,44 +0,0 @@
----
-title: MDX components
-description: Every built-in MDX component, its variants, and its usage.
----
-
-# MDX components
-
-Every component below is available without an import. The examples show every visual variant, so this page is also the reference for the documentation theme.
-
-## Button
-
-`Button` uses the same shadcn component as the theme. It accepts `variant` and `size`, and uses `href` when the button should navigate. Use `align="left"`, `"center"`, or `"right"` to position it in the documentation column.
-
-<Button href="/getting-started" variant="default" size="lg">
-  Get started
-</Button>
-
-## Callout
-
-<Callout type="tip" title="No imports needed">
-  Write built-in components directly in any MDX page.
-</Callout>
-
-## Tabs
-
-<Tabs defaultValue="npm" variant="line">
-  <Tab title="npm">npm install @heyo-sh/heyo-docs</Tab>
-  <Tab title="Bun">bun add @heyo-sh/heyo-docs</Tab>
-</Tabs>
-
-## Code blocks
-
-`CodeBlock` preserves every newline as a hard code line.
-
-<CodeBlock language="ts" title="src/config.ts">
-  {`export const title = "My docs";
-export const searchEnabled = true;`}
-</CodeBlock>
-
-## Mermaid
-
-<Mermaid>{`flowchart LR
-  Content --> Build
-  Build --> Documentation`}</Mermaid>

package/templates/astro/content/openapi-petstore.json

@@ -1,160 +0,0 @@
-{
-  "openapi": "3.0.4",
-  "info": {
-    "title": "Swagger Petstore - OpenAPI 3.0",
-    "description": "A small, read-only extract of the public Swagger Petstore schema for debugging Heyo Docs. Source: https://petstore3.swagger.io/api/v3/openapi.json",
-    "version": "1.0.27",
-    "license": {
-      "name": "Apache 2.0",
-      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
-    }
-  },
-  "servers": [
-    {
-      "url": "https://petstore3.swagger.io/api/v3",
-      "description": "Swagger Petstore public server"
-    }
-  ],
-  "paths": {
-    "/pet/findByStatus": {
-      "get": {
-        "tags": ["pet"],
-        "summary": "Finds Pets by status.",
-        "description": "Multiple status values can be provided with comma separated strings.",
-        "operationId": "findPetsByStatus",
-        "parameters": [
-          {
-            "name": "status",
-            "in": "query",
-            "description": "Status values that need to be considered for filter",
-            "required": true,
-            "explode": true,
-            "schema": {
-              "type": "string",
-              "default": "available",
-              "enum": ["available", "pending", "sold"]
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "successful operation",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": { "$ref": "#/components/schemas/Pet" }
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Invalid status value"
-          },
-          "default": {
-            "description": "Unexpected error"
-          }
-        }
-      }
-    },
-    "/store/order/{orderId}": {
-      "get": {
-        "tags": ["store"],
-        "summary": "Find purchase order by ID.",
-        "description": "For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.",
-        "operationId": "getOrderById",
-        "parameters": [
-          {
-            "name": "orderId",
-            "in": "path",
-            "description": "ID of order that needs to be fetched.",
-            "required": true,
-            "schema": {
-              "type": "integer",
-              "format": "int64"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "successful operation",
-            "content": {
-              "application/json": {
-                "schema": { "$ref": "#/components/schemas/Order" }
-              }
-            }
-          },
-          "400": {
-            "description": "Invalid ID supplied"
-          },
-          "404": {
-            "description": "Order not found"
-          },
-          "default": {
-            "description": "Unexpected error"
-          }
-        }
-      }
-    }
-  },
-  "components": {
-    "schemas": {
-      "Order": {
-        "type": "object",
-        "properties": {
-          "id": { "type": "integer", "format": "int64", "example": 10 },
-          "petId": {
-            "type": "integer",
-            "format": "int64",
-            "example": 198772
-          },
-          "quantity": { "type": "integer", "format": "int32", "example": 7 },
-          "shipDate": { "type": "string", "format": "date-time" },
-          "status": {
-            "type": "string",
-            "description": "Order Status",
-            "example": "approved",
-            "enum": ["placed", "approved", "delivered"]
-          },
-          "complete": { "type": "boolean" }
-        }
-      },
-      "Category": {
-        "type": "object",
-        "properties": {
-          "id": { "type": "integer", "format": "int64", "example": 1 },
-          "name": { "type": "string", "example": "Dogs" }
-        }
-      },
-      "Tag": {
-        "type": "object",
-        "properties": {
-          "id": { "type": "integer", "format": "int64" },
-          "name": { "type": "string" }
-        }
-      },
-      "Pet": {
-        "required": ["name", "photoUrls"],
-        "type": "object",
-        "properties": {
-          "id": { "type": "integer", "format": "int64", "example": 10 },
-          "name": { "type": "string", "example": "doggie" },
-          "category": { "$ref": "#/components/schemas/Category" },
-          "photoUrls": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "tags": {
-            "type": "array",
-            "items": { "$ref": "#/components/schemas/Tag" }
-          },
-          "status": {
-            "type": "string",
-            "description": "pet status in the store",
-            "enum": ["available", "pending", "sold"]
-          }
-        }
-      }
-    }
-  }
-}