@heyo-sh/create-heyo-docs 0.2.0 → 0.2.1

package/README.md

@@ -4,38 +4,30 @@ Create a standalone, production-ready documentation site with Heyo Docs. Choose
 
 ## Create a project
 
+Run the creator without arguments to choose the project directory, framework,
+deployment target, theme, and package manager interactively. It prints the
+appropriate `cd` and development-server commands when it finishes.
+
 ```bash
 # pnpm
-pnpm create @heyo-sh/heyo-docs my-docs
-cd my-docs
-pnpm dev
+pnpm create @heyo-sh/heyo-docs
 
 # npm
-npm create @heyo-sh/heyo-docs@latest my-docs
-cd my-docs
-npm run dev
+npm create @heyo-sh/heyo-docs@latest
 
 # Yarn
-yarn dlx @heyo-sh/create-heyo-docs my-docs
-cd my-docs
-yarn dev
+yarn dlx @heyo-sh/create-heyo-docs
 
 # Bun
-bun create @heyo-sh/heyo-docs my-docs
-cd my-docs
-bun run dev
+bun create @heyo-sh/heyo-docs
 ```
 
 The creator works with pnpm, npm, Yarn, and Bun.
 
 ## Options
 
-```bash
-pnpm create @heyo-sh/heyo-docs my-docs \
-  --template astro \
-  --theme moss \
-  --deployment cloudflare
-```
+Passing options makes the creator non-interactive; include a project-directory
+argument when using them in automation.
 
 | Option              | Values                          |
 | ------------------- | ------------------------------- |

package/package.json

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

package/templates/astro/content/configuration.mdx

@@ -0,0 +1,76 @@
+---
+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.
+
+## 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

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

@@ -0,0 +1,36 @@
+---
+title: Callouts
+description: Highlight prerequisites, tips, warnings, and successful outcomes.
+---
+
+# 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.
+
+## 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.
+
+<Callout type="tip" title="Keep examples focused">
+  Show one idea at a time so readers can apply it quickly.
+</Callout>
+
+<Callout type="warning" title="Preview before publishing">
+  Run the production build locally after changing navigation or MDX.
+</Callout>
+
+## Add richer guidance
+
+Pass the message as children when it needs Markdown or another MDX component.
+
+<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.
+</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

@@ -0,0 +1,51 @@
+---
+title: Code Blocks
+description: Write compact, copyable examples with syntax highlighting and context.
+---
+
+# 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.
+
+## 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.
+
+```bash
+bun run dev
+bun run build
+```
+
+## Give configuration a title
+
+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.
+
+<CodeBlock language="ts" title="heyo-docs.config.ts" showLineNumbers>
+  {`export default heyoDocs({
+  title: "Orbit Docs",
+  content: "content",
+  theme: "grain",
+});`}
+</CodeBlock>
+
+## Compare equivalent commands
+
+Put package-manager variants in a `CodeBlockGroup` so readers can choose one
+command without scrolling past unrelated options.
+
+<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

@@ -0,0 +1,40 @@
+---
+title: Lists
+description: Use ordered, unordered, and task lists to make steps and choices 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 bullets for related options
+
+Use an unordered list when order does not change the result.
+
+- 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
+
+An ordered list makes dependencies explicit.
+
+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
+
+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.
+
+- 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.

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

@@ -0,0 +1,37 @@
+---
+title: Tables
+description: Compare a small, consistent set of options in a documentation 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.
+
+## Compare like with like
+
+For example, a configuration reference can show the setting, its purpose, and
+a representative value.
+
+| 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 cells concise
+
+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 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   |
+
+If a reader must act on the information in a specific order, use a numbered
+list or [Quickstart](/quickstart) instead.

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

@@ -0,0 +1,42 @@
+---
+title: Tabs
+description: Let readers choose between related commands or platform-specific instructions.
+---
+
+# 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.
+
+## 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`.
+
+<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>
+
+## Keep the choices parallel
+
+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.
+
+<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>

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

@@ -0,0 +1,50 @@
+---
+title: Text Styling
+description: Structure documentation with clear 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.
+
+## Build a clear hierarchy
+
+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.
+
+```md
+## Configure navigation
+
+Add pages in the order readers should follow.
+
+### Add an external resource
+
+Use a custom link for a separate destination.
+```
+
+## Emphasize the decision
+
+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.
+
+```md
+Set `content: "content"` in `heyo-docs.config.ts`.
+
+Deploy **after** reviewing the production build.
+```
+
+## Link with context
+
+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.
+
+Read the [Quickstart](/quickstart) before changing the
+[site configuration](/configuration).
+
+> Keep each paragraph focused on one idea so readers can quickly find the
+> decision that applies to them.

package/templates/astro/content/quickstart.mdx

@@ -0,0 +1,60 @@
+---
+title: Quickstart
+description: Create, run, and understand your Heyo Docs project.
+---
+
+# Quickstart
+
+A new Heyo Docs project is a complete documentation site: MDX files provide the
+content, `heyo-docs.config.ts` defines the site model, and your selected
+framework renders the finished experience.
+
+## Create a project
+
+Use the creator with the package manager you already use. It asks for a project
+name, framework, deployment target, theme, and package manager, then creates a
+ready-to-run application.
+
+<CodeBlockGroup defaultValue="bun" variant="line">
+  <CodeBlock language="bash" title="bun">
+    {"bun create @heyo-sh/heyo-docs"}
+  </CodeBlock>
+  <CodeBlock language="bash" title="npm">
+    {"npm create @heyo-sh/heyo-docs@latest"}
+  </CodeBlock>
+  <CodeBlock language="bash" title="pnpm">
+    {"pnpm create @heyo-sh/heyo-docs"}
+  </CodeBlock>
+  <CodeBlock language="bash" title="yarn">
+    {"yarn dlx @heyo-sh/create-heyo-docs"}
+  </CodeBlock>
+</CodeBlockGroup>
+
+When the command finishes, move into the new directory and run the development
+command printed by the creator. The local server rebuilds the documentation
+when you change either content or configuration.
+
+## How the pieces fit together
+
+1. **Content** lives in the `content` directory. Every `.mdx` file becomes a
+   documentation route.
+2. **Configuration** in `heyo-docs.config.ts` gives the site its name, theme,
+   navigation order, and public metadata.
+3. **The framework app** loads the same model during development and production
+   builds, so the sidebar, search, routes, and adjacent-page links stay in sync.
+
+Create a new file such as `content/guides/deployment.mdx` to add the
+`/guides/deployment` route. Add that path to a navigation section when the
+page should appear in the sidebar.
+
+## Make your first change
+
+Update the title and description in the frontmatter of `content/index.mdx`,
+then refresh the browser. Use [Basic Configuration](/configuration) to adjust
+the site model and [Text Styling](/essentials/text-styling) for writing the
+page itself.
+
+<Callout type="tip" title="One source of truth">
+  Keep navigation in <code>heyo-docs.config.ts</code> and page-specific details
+  in MDX frontmatter. The build validates both before publishing.
+</Callout>

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

@@ -12,8 +12,30 @@ export default heyoDocs({
       icon: "globe",
       sections: [
         {
-          section: "Get started",
-          pages: ["index"],
+          pages: [
+            {
+              title: "Documentation",
+              src: "https://docs.heyo.sh/introduction",
+              icon: "book",
+            },
+          ],
+        },
+        {
+          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",
+          ],
         },
       ],
     },

package/templates/next/content/configuration.mdx

@@ -0,0 +1,76 @@
+---
+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.
+
+## 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

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