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

package/package.json

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

package/templates/astro/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/astro/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/astro/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/astro/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/astro/content/configuration.mdx

@@ -64,6 +64,40 @@ 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. `openai`, `claude`, and `grok`
+use the OpenAI, Anthropic, and xAI adapters respectively. Keep the key in a
+server environment variable; Heyo Docs sends it only from the chat endpoint.
+
+<CodeBlock language="ts" title="heyo-docs.config.ts">
+  {`ai: {
+  chat: {
+    provider: "openai",
+    key: process.env.OPENAI_API_KEY!,
+    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`, `key`, and `model` are required. The model must be an actual model
+identifier, not the provider name. `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.

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

@@ -1,36 +1,34 @@
 ---
 title: Callouts
-description: Highlight prerequisites, tips, warnings, and successful outcomes.
+description: Draw attention to a tip, warning, prerequisite, or result.
 ---
 
 # Callouts
 
-Use `Callout` when an important note should stand apart from the surrounding
-prose. It works well for a prerequisite, a preferred approach, a warning, or a
-successful result.
+Use a callout when a reader should not miss a detail.
 
-## Choose the right emphasis
-
-Use `note` or `info` for context, `tip` for a recommended approach, and
-`check` for a completed outcome. Reserve `warning` and `danger` for cases
-where missing the message has a real consequence.
+## 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 locally after changing navigation or MDX.
+  Run the production build after changing navigation or MDX.
 </Callout>
 
-## Add richer guidance
-
-Pass the message as children when it needs Markdown or another MDX component.
+## Keep it short
 
 <Callout type="info" title="Configuration and content work together">
-  Navigation belongs in <code>heyo-docs.config.ts</code>; page titles and
-  descriptions belong in the page frontmatter.
+  Navigation belongs in <code>heyo-docs.config.ts</code>. Titles and
+  descriptions belong in page frontmatter.
 </Callout>
-
-Keep each callout focused on one decision. A long sequence of status messages is
-usually clearer as regular sections or a numbered procedure.

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

@@ -1,29 +1,22 @@
 ---
 title: Code Blocks
-description: Write compact, copyable examples with syntax highlighting and context.
+description: Add clear, copyable commands and configuration examples.
 ---
 
 # Code Blocks
 
-A code example should answer one implementation question and be safe to copy.
-Use inline code for a literal value, then use a fenced block or `CodeBlock`
-when a reader needs more than one line.
+Show one task per example. Add a language so the code is easy to read.
 
-## Add a language to fenced code
-
-The language label enables syntax highlighting and tells readers what they are
-looking at. Use `bash` for commands, `ts` for configuration, and `json` for
-data.
+## Add a command
 
 ```bash
 bun run dev
 bun run build
 ```
 
-## Give configuration a title
+## Add a file name
 
-Use `CodeBlock` when a sample needs a filename or line numbers. Keep examples
-small enough that a reader can understand their effect before copying them.
+Use `CodeBlock` when the file name helps explain where the code belongs.
 
 <CodeBlock language="ts" title="heyo-docs.config.ts" showLineNumbers>
   {`export default heyoDocs({
@@ -33,10 +26,9 @@ small enough that a reader can understand their effect before copying them.
 });`}
 </CodeBlock>
 
-## Compare equivalent commands
+## Show alternatives
 
-Put package-manager variants in a `CodeBlockGroup` so readers can choose one
-command without scrolling past unrelated options.
+Use `CodeBlockGroup` for equivalent commands, such as package managers.
 
 <CodeBlockGroup defaultValue="bun" variant="line">
   <CodeBlock language="bash" title="bun">

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

@@ -1,40 +1,36 @@
 ---
 title: Lists
-description: Use ordered, unordered, and task lists to make steps and choices easy to scan.
+description: Use lists to make choices and short steps easy to scan.
 ---
 
 # Lists
 
-Lists make a page easier to scan when readers need to compare options, follow a
-short sequence, or check completion. Keep every item parallel in structure and
-start it with the action or noun that matters most.
+Use a list when readers need to scan choices or follow a short sequence.
 
-## Use bullets for related options
+## Add a bullet list
 
-Use an unordered list when order does not change the result.
+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.
 
-## Use numbers when sequence matters
+## Add numbered steps
 
-An ordered list makes dependencies explicit.
+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.
 
-## Keep nested lists intentional
+## Add one level when needed
 
-Use a nested list only to clarify a direct relationship. Too many levels make
-the page harder to scan than a short heading and paragraph.
+Use a nested list only for a direct relationship.
 
 - Prepare the release:
   - Review the changed pages.
   - Confirm navigation order.
   - Run the production build.
 
-Use a `Steps` component instead when each item needs rich content such as a
-command, callout, or additional explanation.
+Use `Steps` when each step needs a command or more explanation.

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

@@ -1,18 +1,13 @@
 ---
 title: Tables
-description: Compare a small, consistent set of options in a documentation table.
+description: Compare a small set of options with a simple Markdown table.
 ---
 
 # Tables
 
-Use a table when readers need to compare the same attributes across a small
-number of options. Tables are strongest when every cell is short and each row
-can be understood without a paragraph of surrounding prose.
+Use a table to compare the same details across a small number of options.
 
-## Compare like with like
-
-For example, a configuration reference can show the setting, its purpose, and
-a representative value.
+## Add a table
 
 | Setting   | Purpose                                | Example                      |
 | --------- | -------------------------------------- | ---------------------------- |
@@ -21,11 +16,10 @@ a representative value.
 | `mode`    | Initial color preference.              | `"system"`                   |
 | `siteUrl` | Canonical public site origin.          | `"https://docs.example.com"` |
 
-## Keep cells concise
+## Keep it readable
 
-Move long explanations, procedures, and code samples out of the table. Link to
-a focused guide instead of stretching a table past the point where it can be
-read horizontally.
+Use short headings and short cells. Put long explanations in a section below
+the table.
 
 | Use a table for        | Use a section for      |
 | ---------------------- | ---------------------- |
@@ -33,5 +27,4 @@ read horizontally.
 | Option defaults        | A detailed explanation |
 | Short reference values | A large code example   |
 
-If a reader must act on the information in a specific order, use a numbered
-list or [Quickstart](/quickstart) instead.
+Use a numbered list when readers must act in a specific order.

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

@@ -1,18 +1,14 @@
 ---
 title: Tabs
-description: Let readers choose between related commands or platform-specific instructions.
+description: Let readers switch between equivalent commands or platforms.
 ---
 
 # Tabs
 
-`Tabs` presents related content one panel at a time. It is useful for package
-manager commands, framework variants, and small comparisons where readers need
-only one option to complete the task.
+Use tabs for equivalent ways to complete the same task. Keep their labels
+short.
 
-## Label equivalent choices clearly
-
-Each `Tab` needs a concise title. Give a tab a stable `value` when you need
-to set a different initial panel with `defaultValue`.
+## Add tabs
 
 <Tabs defaultValue="typescript" variant="line">
   <Tab title="JavaScript" value="javascript">
@@ -23,11 +19,9 @@ to set a different initial panel with `defaultValue`.
   </Tab>
 </Tabs>
 
-## Keep the choices parallel
+## Compare platforms
 
-Tabs work when every panel solves the same problem in a different environment.
-Use headings or `Steps` for a sequence that every reader must complete; tabs
-can hide required information.
+Each tab should answer the same question for a different platform.
 
 <Tabs defaultValue="vercel" variant="line">
   <Tab title="Vercel" value="vercel">
@@ -40,3 +34,7 @@ can hide required information.
     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,19 +1,16 @@
 ---
 title: Text Styling
-description: Structure documentation with clear headings, emphasis, links, and quotes.
+description: Use simple Markdown for headings, emphasis, links, and quotes.
 ---
 
 # Text Styling
 
-Good documentation is easy to scan before it is read in detail. Use the
-frontmatter title for the page's H1, then organize the body around short,
-descriptive H2 and H3 headings.
+Use regular Markdown for most documentation. Keep the text short and let
+headings show readers where to look next.
 
-## Build a clear hierarchy
+## Add headings
 
-Use `##` for the main tasks or ideas on a page. Add `###` only when a section
-has a meaningful subdivision. Headings should tell the reader what they will
-learn, not simply announce that more information follows.
+Use `##` for a main section and `###` only for a useful subsection.
 
 ```md
 ## Configure navigation
@@ -22,29 +19,25 @@ Add pages in the order readers should follow.
 
 ### Add an external resource
 
-Use a custom link for a separate destination.
+Link to a resource outside your documentation.
 ```
 
-## Emphasize the decision
+## Highlight important text
 
-Use **bold text** for an important choice and inline `code` for literal values
-such as file names, commands, and configuration keys. Keep the rest of the
-sentence plain so these signals remain useful.
+Use **bold** for an important choice and inline `code` for values readers need
+to copy.
 
 ```md
 Set `content: "content"` in `heyo-docs.config.ts`.
 
-Deploy **after** reviewing the production build.
+Run `bun run build` before you publish.
 ```
 
-## Link with context
+## Write useful links
 
-Describe where a link goes instead of pasting a raw URL. Relative links work
-well for another page in the same documentation, while full URLs are useful for
-external resources.
+Use the destination as the link text. It is easier to scan than a raw URL.
 
-Read the [Quickstart](/quickstart) before changing the
+Read the [Quickstart](/quickstart) before changing
 [site configuration](/configuration).
 
-> Keep each paragraph focused on one idea so readers can quickly find the
-> decision that applies to them.
+> Keep one idea in each short paragraph.

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

@@ -0,0 +1,160 @@
+{
+  "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"]
+          }
+        }
+      }
+    }
+  }
+}