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

package/README.md

@@ -0,0 +1,44 @@
+# Create Heyo Docs
+
+Create a standalone, production-ready documentation site with Heyo Docs. Choose React Router, Next.js, or Astro, plus a built-in theme and deployment target.
+
+## 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
+
+# npm
+npm create @heyo-sh/heyo-docs@latest
+
+# Yarn
+yarn dlx @heyo-sh/create-heyo-docs
+
+# Bun
+bun create @heyo-sh/heyo-docs
+```
+
+The creator works with pnpm, npm, Yarn, and Bun.
+
+## Options
+
+Passing options makes the creator non-interactive; include a project-directory
+argument when using them in automation.
+
+| Option              | Values                          |
+| ------------------- | ------------------------------- |
+| `--template`        | `react-router`, `next`, `astro` |
+| `--theme`           | `grain`, `shade`, `moss`        |
+| `--deployment`      | `cloudflare`, `vercel`, `later` |
+| `--package-manager` | `bun`, `pnpm`, `npm`, `yarn`    |
+| `--no-install`      | Skip dependency installation    |
+
+Read the [full documentation](https://docs.heyo.sh) for configuration, content, components, framework integrations, and deployment.
+
+## License
+
+[MIT](https://github.com/heyo-sh/heyo-docs/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import type { CreateOptions } from "./types";
+export { detectPackageManager, packageManagerField, packageManagerRunCommand, } from "./package-manager";
+export { scaffoldProject } from "./scaffold";
+export { mergePackageJson, replacePlaceholders } from "./utils";
+export type * from "./types";
+export declare function run(argv?: string[]): Promise<void>;
+export declare function parseArguments(argv: string[]): {
+    options: CreateOptions;
+    interactive: boolean;
+    showHelp: boolean;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAChE,mBAAmB,SAAS,CAAC;AAqD7B,wBAAsB,GAAG,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBrE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC9C,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAsDA"}

package/dist/index.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+
+// src/package-manager.ts
+import { spawnSync } from "node:child_process";
+var FALLBACK_VERSIONS = {
+  bun: "1.3.1",
+  pnpm: "10.17.0",
+  npm: "11.6.0",
+  yarn: "4.9.4"
+};
+function detectPackageManager(userAgent = process.env.npm_config_user_agent ?? "") {
+  const match = userAgent.match(/(?:^|\s)(bun|pnpm|npm|yarn)\/([^\s]+)/);
+  if (!match)
+    return { name: "npm" };
+  return { name: match[1], version: match[2] };
+}
+function packageManagerField(manager, detected = detectPackageManager()) {
+  if (manager === detected.name && detected.version)
+    return `${manager}@${detected.version}`;
+  const executable = manager === "yarn" ? "yarn" : manager;
+  try {
+    const result = spawnSync(executable, ["--version"], {
+      encoding: "utf8"
+    });
+    const version = result.stdout?.trim();
+    if (result.status === 0 && version && /^\d+(?:\.\d+)+/.test(version))
+      return `${manager}@${version}`;
+  } catch {}
+  return `${manager}@${FALLBACK_VERSIONS[manager]}`;
+}
+function packageManagerInstallCommand(manager) {
+  return manager === "yarn" ? ["yarn"] : [manager, "install"];
+}
+function packageManagerRunCommand(manager, script) {
+  if (manager === "npm")
+    return `npm run ${script}`;
+  if (manager === "yarn")
+    return `yarn ${script}`;
+  return `${manager} run ${script}`;
+}
+
+// src/project-name.ts
+var PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/i;
+function projectNameError(value) {
+  if (!value.trim())
+    return "Enter a project name.";
+  if (!PROJECT_NAME_PATTERN.test(value))
+    return "Use letters, numbers and hyphens only.";
+}
+function assertProjectName(value) {
+  const error = projectNameError(value);
+  if (error)
+    throw new Error(error);
+  return value.trim();
+}
+
+// src/scaffold.ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir as mkdir2, readdir as readdir2 } from "node:fs/promises";
+import { join as join2, resolve } from "node:path";
+
+// src/utils.ts
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  writeFile
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+function replacePlaceholders(source, values) {
+  return source.replace(/\{\{([A-Z0-9_]+)\}\}/g, (placeholder, key) => values[key] ?? placeholder);
+}
+function mergePackageJson(base, overlay) {
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const current = merged[key];
+    if (isRecord(current) && isRecord(value))
+      merged[key] = mergePackageJson(current, value);
+    else
+      merged[key] = value;
+  }
+  return merged;
+}
+async function copyTemplate(source, destination, placeholders) {
+  await cp(source, destination, { recursive: true, force: true });
+  await replacePlaceholdersAtPath(destination, placeholders);
+}
+async function replacePlaceholdersAtPath(path, values) {
+  if (!(await stat(path)).isDirectory()) {
+    const contents = await readFile(path, "utf8");
+    await writeFile(path, replacePlaceholders(contents, values));
+    return;
+  }
+  const entries = await readdir(path, { withFileTypes: true });
+  await Promise.all(entries.map((entry) => replacePlaceholdersAtPath(join(path, entry.name), values)));
+}
+async function writeJson(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(data, null, 2)}
+`);
+}
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/scaffold.ts
+var packageRoot = resolve(import.meta.dirname, "..");
+async function scaffoldProject(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const projectName = assertProjectName(options.projectName);
+  const projectPath = resolve(cwd, projectName);
+  if (existsSync(projectPath))
+    throw new Error(`Directory already exists: ${projectPath}`);
+  const placeholders = {
+    PROJECT_NAME: projectName,
+    HEYO_DOCS_VERSION: options.heyoDocsVersion ?? "0.1.0",
+    PACKAGE_MANAGER: packageManagerField(options.packageManager),
+    THEME: options.theme
+  };
+  const templatePath = join2(packageRoot, "templates", options.template);
+  const deploymentPath = join2(packageRoot, "deployments", options.deployment, options.template);
+  await mkdir2(projectPath, { recursive: true });
+  await copyTemplate(templatePath, projectPath, placeholders);
+  const basePackage = await readJson(join2(projectPath, "package.json"));
+  const overlayPackage = options.deployment === "later" ? {} : await readJson(join2(deploymentPath, "package.json"));
+  if (options.deployment !== "later") {
+    await copyOverlay(deploymentPath, projectPath, placeholders);
+  }
+  await writeJson(join2(projectPath, "package.json"), mergePackageJson(basePackage, overlayPackage));
+  if (options.install)
+    await installDependencies(projectPath, options.packageManager);
+  return { projectPath };
+}
+async function copyOverlay(source, destination, placeholders) {
+  const entries = await readdir2(source, { withFileTypes: true });
+  await Promise.all(entries.filter((entry) => entry.name !== "package.json").map(async (entry) => {
+    const sourcePath = join2(source, entry.name);
+    const destinationPath = join2(destination, entry.name);
+    return copyTemplate(sourcePath, destinationPath, placeholders);
+  }));
+}
+async function installDependencies(projectPath, packageManager) {
+  const command = packageManagerInstallCommand(packageManager);
+  const [executable, ...arguments_] = command;
+  await new Promise((resolveInstall, rejectInstall) => {
+    const child = spawn(executable, arguments_, {
+      cwd: projectPath,
+      stdio: "inherit"
+    });
+    child.once("error", rejectInstall);
+    child.once("close", (exitCode) => {
+      if (exitCode === 0)
+        return resolveInstall();
+      rejectInstall(new Error(`Dependency installation failed with ${command.join(" ")}.`));
+    });
+  });
+}
+
+// src/index.ts
+var USAGE = "Usage: create-heyo-docs [project-name] [--template react-router|next|astro] [--deployment cloudflare|vercel|later] [--theme grain|shade|moss] [--package-manager bun|pnpm|npm|yarn] [--no-install]";
+var TEMPLATE_OPTIONS = [
+  { value: "react-router", label: "React Router" },
+  { value: "next", label: "Next.js" },
+  { value: "astro", label: "Astro" }
+];
+var DEPLOYMENT_OPTIONS = [
+  { value: "cloudflare", label: "Cloudflare" },
+  { value: "vercel", label: "Vercel" },
+  { value: "later", label: "Configure later" }
+];
+var THEME_OPTIONS = [
+  { value: "grain", label: "Grain" },
+  { value: "shade", label: "Shade" },
+  { value: "moss", label: "Moss" },
+  {
+    value: "dripper",
+    label: "Dripper — Soon",
+    hint: "Unavailable in this MVP"
+  },
+  {
+    value: "fixed-gear",
+    label: "Fixed Gear — Soon",
+    hint: "Unavailable in this MVP"
+  }
+];
+var PACKAGE_MANAGER_OPTIONS = [
+  { value: "bun", label: "bun" },
+  { value: "pnpm", label: "pnpm" },
+  { value: "npm", label: "npm" },
+  { value: "yarn", label: "yarn" }
+];
+if (isMainModule()) {
+  run(process.argv.slice(2)).catch((error) => {
+    p.log.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}
+function isMainModule() {
+  const entryPoint = process.argv[1];
+  if (!entryPoint)
+    return false;
+  try {
+    return realpathSync(entryPoint) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+async function run(argv = process.argv.slice(2)) {
+  const parsed = parseArguments(argv);
+  if (parsed.showHelp) {
+    p.note(USAGE, "@heyo-sh/create-heyo-docs");
+    return;
+  }
+  const options = parsed.interactive ? await askQuestions(parsed.options) : parsed.options;
+  const spinner2 = p.spinner();
+  spinner2.start("Creating your Heyo Docs project");
+  try {
+    await scaffoldProject(options);
+  } catch (error) {
+    spinner2.stop("Unable to create your documentation project");
+    throw error;
+  }
+  spinner2.stop("Your documentation project is ready");
+  const install = options.install ? "" : `
+${options.packageManager} install`;
+  p.note(`cd ${options.projectName}${install}
+${packageManagerRunCommand(options.packageManager, "dev")}`, "Next steps");
+  p.outro("Happy documenting.");
+}
+function parseArguments(argv) {
+  const detected = detectPackageManager();
+  const options = {
+    projectName: "",
+    template: "react-router",
+    deployment: "later",
+    theme: "grain",
+    packageManager: detected.name,
+    install: true
+  };
+  let explicit = false;
+  let showHelp = false;
+  for (let index = 0;index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("-")) {
+      options.projectName ||= value;
+      continue;
+    }
+    explicit = true;
+    if (value === "--template") {
+      options.template = readEnum(argv[++index], ["react-router", "next", "astro"], "template");
+    } else if (value === "--deployment") {
+      options.deployment = readEnum(argv[++index], ["cloudflare", "vercel", "later"], "deployment");
+    } else if (value === "--theme") {
+      options.theme = readEnum(argv[++index], ["grain", "shade", "moss"], "theme");
+    } else if (value === "--package-manager") {
+      options.packageManager = readEnum(argv[++index], ["bun", "pnpm", "npm", "yarn"], "package manager");
+    } else if (value === "--no-install") {
+      options.install = false;
+    } else if (value === "--install") {
+      options.install = true;
+    } else if (value === "--help" || value === "-h") {
+      showHelp = true;
+    } else {
+      throw new Error(`Unknown option: ${value}`);
+    }
+  }
+  return { options, interactive: !explicit && !options.projectName, showHelp };
+}
+async function askQuestions(defaults) {
+  p.intro("Create Heyo Docs");
+  const projectName = await p.text({
+    message: "Project name",
+    placeholder: "my-docs",
+    defaultValue: "my-docs",
+    validate: projectNameError
+  });
+  if (p.isCancel(projectName))
+    cancelCreation();
+  const template = await selectAvailable("Template", TEMPLATE_OPTIONS, [
+    "react-router",
+    "next",
+    "astro"
+  ]);
+  const deployment = await selectAvailable("Deployment", DEPLOYMENT_OPTIONS, ["cloudflare", "vercel", "later"], defaults.deployment);
+  const theme = await selectAvailable("Theme", THEME_OPTIONS, [
+    "grain",
+    "shade",
+    "moss"
+  ]);
+  const packageManager = await selectAvailable("Package manager", PACKAGE_MANAGER_OPTIONS, ["bun", "pnpm", "npm", "yarn"], defaults.packageManager);
+  const install = await p.confirm({
+    message: "Install dependencies?",
+    initialValue: true
+  });
+  if (p.isCancel(install))
+    cancelCreation();
+  return {
+    projectName,
+    template,
+    deployment,
+    theme,
+    packageManager,
+    install
+  };
+}
+async function selectAvailable(message, options, available, initialValue) {
+  for (;; ) {
+    const answer = await p.select({ message, options, initialValue });
+    if (p.isCancel(answer))
+      cancelCreation();
+    if (isOneOf(answer, available))
+      return answer;
+    p.log.warn("That option is planned but not available in this MVP.");
+  }
+}
+function isOneOf(value, values) {
+  return values.some((candidate) => candidate === value);
+}
+function cancelCreation() {
+  p.cancel("Creation cancelled.");
+  process.exit(0);
+}
+function readEnum(value, allowed, label) {
+  if (value && isOneOf(value, allowed))
+    return value;
+  throw new Error(`Use one of ${allowed.join(", ")} for ${label}.`);
+}
+export {
+  scaffoldProject,
+  run,
+  replacePlaceholders,
+  parseArguments,
+  packageManagerRunCommand,
+  packageManagerField,
+  mergePackageJson,
+  detectPackageManager
+};

package/dist/package-manager.d.ts

@@ -0,0 +1,6 @@
+import type { DetectedPackageManager, PackageManager } from "./types";
+export declare function detectPackageManager(userAgent?: string): DetectedPackageManager;
+export declare function packageManagerField(manager: PackageManager, detected?: DetectedPackageManager): string;
+export declare function packageManagerInstallCommand(manager: PackageManager): string[];
+export declare function packageManagerRunCommand(manager: PackageManager, script: string): string;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/package-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../src/package-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAStE,wBAAgB,oBAAoB,CAClC,SAAS,SAA0C,GAClD,sBAAsB,CAIxB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,QAAQ,yBAAyB,GAChC,MAAM,CAeR;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE,CAEV;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,GACb,MAAM,CAIR"}

package/dist/project-name.d.ts

@@ -0,0 +1,3 @@
+export declare function projectNameError(value: string): string | undefined;
+export declare function assertProjectName(value: string): string;
+//# sourceMappingURL=project-name.d.ts.map

package/dist/project-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-name.d.ts","sourceRoot":"","sources":["../src/project-name.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD"}

package/dist/scaffold.d.ts

@@ -0,0 +1,5 @@
+import type { CreateOptions } from "./types";
+export declare function scaffoldProject(options: CreateOptions): Promise<{
+    projectPath: string;
+}>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA0ClC"}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export type Template = "react-router" | "next" | "astro";
+export type Deployment = "cloudflare" | "vercel" | "later";
+export type Theme = "grain" | "shade" | "moss";
+export type PackageManager = "bun" | "pnpm" | "npm" | "yarn";
+export interface CreateOptions {
+    projectName: string;
+    template: Template;
+    deployment: Deployment;
+    theme: Theme;
+    packageManager: PackageManager;
+    install: boolean;
+    cwd?: string;
+    heyoDocsVersion?: string;
+}
+export interface DetectedPackageManager {
+    name: PackageManager;
+    version?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+export declare function replacePlaceholders(source: string, values: Record<string, string>): string;
+export declare function mergePackageJson<T extends Record<string, unknown>>(base: T, overlay: Record<string, unknown>): T;
+export declare function copyTemplate(source: string, destination: string, placeholders: Record<string, string>): Promise<void>;
+export declare function replacePlaceholdersInDirectory(directory: string, values: Record<string, string>): Promise<void>;
+export declare function writeJson(path: string, data: unknown): Promise<void>;
+export declare function readJson<T>(path: string): Promise<T>;
+export declare function emptyDirectory(path: string): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAWA,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,CAAC,CASH;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAOf;AAoBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE1D;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyo-sh/create-heyo-docs",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Create a standalone Heyo Docs documentation project.",
   "homepage": "https://heyo.sh",
   "repository": {
@@ -12,6 +12,9 @@
   },
   "license": "MIT",
   "type": "module",
+  "engines": {
+    "node": ">=20.11.0"
+  },
   "bin": {
     "create-heyo-docs": "./dist/index.js"
   },
@@ -28,7 +31,7 @@
   },
   "scripts": {
     "dev": "bun run build --watch",
-    "build": "bun build src/index.ts --outdir dist --target bun --external @clack/prompts && bun run build:types",
+    "build": "bun build src/index.ts --outdir dist --target node --external @clack/prompts && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "bun test"

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.