docs: Initial documentation structure and baseline content

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/README.md

@@ -0,0 +1,54 @@
+# Clack Documentation
+
+This directory contains the documentation for Clack, a modern, accessible command-line interface builder for Node.js.
+
+## Contributing
+
+To contribute to the documentation:
+
+1. Fork the repository
+2. Make your changes
+3. Submit a pull request
+
+### Adding New Pages
+
+To add a new page to the documentation:
+
+1. Create a new Markdown file in the appropriate language directory (e.g., `en/`)
+2. Add frontmatter with `title` and `description`
+3. Update `config.json` to include the new page in the sidebar
+
+Example frontmatter:
+
+```md
+---
+title: My New Page
+description: Description of my new page
+---
+
+# My New Page
+
+Content goes here...
+```
+
+### Editing Existing Pages
+
+To edit an existing page:
+
+1. Find the page in the appropriate language directory
+2. Make your changes
+3. Submit a pull request
+
+## Integration with bomb.sh
+
+This documentation is designed to be integrated with the bomb.sh website. The content in this directory will be pulled into the `/docs/clack/` route in the bomb.sh repository.
+
+## Local Development
+
+To preview the documentation locally, you'll need to clone the bomb.sh repository and set up the integration. Follow these steps:
+
+1. Clone the bomb.sh repository
+2. Set up the integration to pull in this documentation
+3. Run the development server
+
+See the bomb.sh repository for more detailed instructions on local development.

docs/astro.config.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import ecTwoSlash from "expressive-code-twoslash";
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: "Clack",
+			customCss: [
+				// Relative path to your @font-face CSS file.
+				"./src/fonts/font-face.css",
+			],
+			logo: {
+				dark: "./src/assets/clack-logo.png",
+				light: "./src/assets/clack-logo.png",
+			},
+			components: {
+				Head: "./src/starlightOverrides/Head.astro",
+			},
+			expressiveCode: {
+				plugins: [ecTwoSlash()],
+			},
+			editLink: {
+				baseUrl: "https://github.com/bombshell-dev/clack/docs/edit/main/",
+			},
+			social: {
+				discord: "https://bomb.sh/chat",
+				blueSky: "https://bomb.sh/on/bluesky",
+				github: "https://bomb.sh/on/github",
+			},
+			sidebar: [
+				{
+					label: "Basics",
+					autogenerate: { directory: "basics" },
+				},
+				{
+					label: "Packages",
+					autogenerate: { directory: "packages" },
+				},
+				{
+					label: "Guides",
+					autogenerate: { directory: "guides" },
+				},
+			],
+		}),
+	],
+});

docs/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "clack-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.32.2",
+    "@clack/core": "workspace:*",
+    "@clack/prompts": "workspace:*",
+    "astro": "^5.1.5",
+    "expressive-code-twoslash": "^0.4.0",
+    "sharp": "^0.33.5"
+  }
+}

docs/public/_redirects

@@ -0,0 +1,5 @@
+/on/github https://github.com/bombshell-dev
+/on/bluesky https://bsky.app/profile/bomb.sh
+
+/chat https://discord.gg/2uEVGZSkjX
+/sponsor https://polar.sh/bombshell-dev

docs/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

docs/src/content/docs/basics/getting-started.mdx

@@ -0,0 +1,144 @@
+---
+title: Getting Started
+description: Learn how to get started with Clack
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Clack is a modern, flexible and powerful CLI library that helps you build beautiful command-line interfaces with ease. It provides a set of high-level components and low-level primitives that make it simple to create interactive command-line applications.
+
+## Features
+
+- 🎨 Beautiful, modern UI components
+- 🎯 Type-safe with full TypeScript support
+- 🎭 Customizable styling and theming
+- 🎮 Interactive prompts and menus
+- 🎪 Progressive disclosure
+- 🎭 Form validation
+- 🎯 Error handling
+- 🎨 Consistent styling
+
+## Installation
+
+You can install Clack using npm, yarn, or pnpm:
+
+<Tabs>
+	<TabItem label="npm" icon="seti:npm">
+		```bash
+		npm install @clack/prompts
+		```
+	</TabItem>
+	<TabItem label="pnpm" icon="pnpm">
+		```bash
+		pnpm add @clack/prompts
+		```
+	</TabItem>
+	<TabItem label="Yarn" icon="seti:yarn">
+		```bash
+		yarn add @clack/prompts
+		```
+	</TabItem>
+</Tabs>
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```ts twoslash
+// @errors: 2731
+import { text, select, confirm, isCancel } from '@clack/prompts';
+
+async function main() {
+  // Get user's name
+  const name = await text({
+    message: 'What is your name?',
+    placeholder: 'John Doe',
+  }) as string;
+
+  // Get user's preferred framework
+  const framework = await select({
+    message: 'Choose a framework:',
+    options: [
+      { value: 'react', label: 'React' },
+      { value: 'vue', label: 'Vue' },
+      { value: 'svelte', label: 'Svelte' },
+    ],
+  });
+
+  if (isCancel(framework)) {
+    console.log('Operation cancelled');
+    process.exit(0);
+  }
+
+  // Confirm the selection
+  const shouldProceed = await confirm({
+    message: `Create a ${framework} project for ${name}?`,
+  });
+
+  if (shouldProceed) {
+    console.log('Creating project...');
+  }
+}
+```
+
+## Core Concepts
+
+### High-Level Components
+
+Clack provides several high-level components that make it easy to build interactive CLIs:
+
+- `text()` - For text input with validation
+- `select()` - For selection menus
+- `confirm()` - For yes/no confirmations
+- `multiselect()` - For multiple selections
+- `note()` - For displaying information
+- `spinner()` - For loading states
+
+### Low-Level Primitives
+
+For more control, you can use the low-level primitives:
+
+```ts twoslash
+import { TextPrompt, isCancel } from '@clack/core';
+
+const p = new TextPrompt({
+  render() {
+    return `What's your name?\n${this.valueWithCursor}`;
+  },
+});
+
+const name = await p.prompt();
+if (isCancel(name)) {
+  process.exit(0);
+}
+```
+
+## Next Steps
+
+1. Check out our [Examples](/guides/examples) for more practical use cases
+2. Learn about [Best Practices](/guides/best-practices) for building CLIs
+3. Explore the [API Reference](/api) for detailed documentation
+4. Join our [Discord community](https://bomb.sh/chat) for support and discussions
+
+## TypeScript Support
+
+Clack is built with TypeScript and provides full type safety. All components and primitives are properly typed, making it easy to catch errors at compile time.
+
+```ts twoslash
+import { text } from '@clack/prompts';
+
+// TypeScript will ensure the validation function returns the correct type
+const age = await text({
+  message: 'Enter your age:',
+  validate: (value: string) => {
+    const num = parseInt(value);
+    if (isNaN(num)) return 'Please enter a valid number';
+    if (num < 0 || num > 120) return 'Age must be between 0 and 120';
+    return undefined;
+  },
+});
+```
+
+## Contributing
+
+We welcome contributions! Please check out our [Contributing Guide](/contributing) for details on our code of conduct and the process for submitting pull requests.