@aravindc26/velu 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# Velu
+
+A modern documentation site generator. Write Markdown, configure with JSON, ship a beautiful docs site.
+
+## Install
+
+```bash
+npm install -g github:YOUR_USERNAME/velu
+```
+
+## Quick Start
+
+1. Create a directory with your docs:
+
+```
+my-docs/
+  velu.json
+  quickstart.md
+  guides/
+    installation.md
+    editor.md
+```
+
+2. Define your navigation in `velu.json`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/YOUR_USERNAME/velu/main/schema/velu.schema.json",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "API Reference",
+        "pages": ["api-reference/get", "api-reference/post"]
+      }
+    ],
+    "groups": [
+      {
+        "group": "Getting Started",
+        "pages": ["quickstart", "guides/installation"]
+      }
+    ]
+  }
+}
+```
+
+3. Run the dev server:
+
+```bash
+cd my-docs
+velu run
+```
+
+Your site is live at `http://localhost:4321`.
+
+## CLI Commands
+
+| Command              | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `velu lint`          | Validate `velu.json` and check referenced pages  |
+| `velu run`           | Build and start the dev server (default port 4321)|
+| `velu run --port N`  | Start on a custom port                           |
+| `velu build`         | Build the site without starting a server         |
+
+## Navigation
+
+Velu supports three levels of navigation hierarchy:
+
+### Tabs
+
+Top-level horizontal navigation rendered in the header.
+
+```json
+{
+  "tab": "SDKs",
+  "pages": ["sdk/fetch", "sdk/create"]
+}
+```
+
+External link tabs:
+
+```json
+{
+  "tab": "Blog",
+  "href": "https://blog.example.com"
+}
+```
+
+### Groups
+
+Collapsible sidebar groups containing pages or nested groups.
+
+```json
+{
+  "group": "Getting Started",
+  "pages": ["quickstart", "installation"]
+}
+```
+
+### Pages
+
+Reference markdown files by their path relative to the docs directory, without the `.md` extension:
+
+```
+"quickstart"           → quickstart.md
+"guides/installation"  → guides/installation.md
+```
+
+## File Watching
+
+During `velu run`, changes to `.md` files and `velu.json` in the docs directory are automatically synced and hot-reloaded — no restart needed.
+
+## License
+
+MIT

package/bin/velu.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(__dirname, "..", "src", "cli.ts");
+
+const child = spawn(
+  process.execPath,
+  ["--import", "tsx", cliPath, ...process.argv.slice(2)],
+  { stdio: "inherit", cwd: process.cwd() }
+);
+
+child.on("exit", (code) => process.exit(code ?? 1));
+
+process.on("SIGINT", () => child.kill("SIGINT"));
+process.on("SIGTERM", () => child.kill("SIGTERM"));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aravindc26/velu",
+  "version": "0.1.0",
+  "description": "A modern documentation site generator powered by Markdown and JSON configuration",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["docs", "documentation", "markdown", "static-site", "cli"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "velu": "./bin/velu.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "schema/"
+  ],
+  "scripts": {
+    "lint": "tsx src/cli.ts lint",
+    "build": "tsx src/cli.ts build",
+    "dev": "tsx src/cli.ts run"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/schema/velu.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://velu.dev/schema/velu.schema.json",
+  "title": "Velu Configuration",
+  "description": "Configuration schema for velu.json — the core config file for Velu documentation sites.",
+  "type": "object",
+  "required": ["navigation"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL to the JSON schema for editor validation."
+    },
+    "navigation": {
+      "type": "object",
+      "description": "Defines the site navigation hierarchy: tabs → groups → pages.",
+      "properties": {
+        "tabs": {
+          "type": "array",
+          "description": "Top-level navigation tabs.",
+          "items": {
+            "$ref": "#/definitions/tab"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Top-level navigation groups (used when there are no tabs, or as default content).",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "description": "Top-level standalone pages.",
+          "items": {
+            "$ref": "#/definitions/page"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "page": {
+      "type": "string",
+      "description": "Reference to a markdown file relative to the docs directory (without .md extension). E.g. 'quickstart' → docs/quickstart.md, 'writing-content/page' → docs/writing-content/page.md."
+    },
+    "group": {
+      "type": "object",
+      "description": "A group of pages, optionally nested.",
+      "required": ["group", "pages"],
+      "properties": {
+        "group": {
+          "type": "string",
+          "description": "Display name for the group."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon identifier for the group."
+        },
+        "tag": {
+          "type": "string",
+          "description": "Optional badge/tag label displayed next to the group name."
+        },
+        "expanded": {
+          "type": "boolean",
+          "description": "Whether the group is expanded by default. Defaults to true.",
+          "default": true
+        },
+        "pages": {
+          "type": "array",
+          "description": "Pages or nested groups within this group.",
+          "items": {
+            "oneOf": [
+              { "$ref": "#/definitions/page" },
+              { "$ref": "#/definitions/group" }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "tab": {
+      "type": "object",
+      "description": "A top-level navigation tab.",
+      "required": ["tab"],
+      "properties": {
+        "tab": {
+          "type": "string",
+          "description": "Display name for the tab."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon identifier for the tab."
+        },
+        "href": {
+          "type": "string",
+          "description": "External link URL. When set, the tab links externally instead of showing pages.",
+          "format": "uri"
+        },
+        "pages": {
+          "type": "array",
+          "description": "Standalone pages directly under this tab.",
+          "items": {
+            "$ref": "#/definitions/page"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups of pages under this tab.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        }
+      },
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": ["href"],
+          "not": {
+            "anyOf": [
+              { "required": ["pages"] },
+              { "required": ["groups"] }
+            ]
+          }
+        },
+        {
+          "not": { "required": ["href"] },
+          "anyOf": [
+            { "required": ["pages"] },
+            { "required": ["groups"] }
+          ]
+        }
+      ]
+    }
+  }
+}

package/src/build.ts

@@ -0,0 +1,637 @@
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, rmSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+
+// ── Types (used only by build.ts for page copying) ─────────────────────────────
+
+interface VeluGroup {
+  group: string;
+  pages: (string | VeluGroup)[];
+}
+
+interface VeluTab {
+  tab: string;
+  href?: string;
+  pages?: string[];
+  groups?: VeluGroup[];
+}
+
+interface VeluConfig {
+  $schema?: string;
+  navigation: {
+    tabs?: VeluTab[];
+    groups?: VeluGroup[];
+    pages?: string[];
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function loadConfig(docsDir: string): VeluConfig {
+  const raw = readFileSync(join(docsDir, "velu.json"), "utf-8");
+  return JSON.parse(raw);
+}
+
+function pageLabelFromSlug(slug: string): string {
+  const last = slug.split("/").pop()!;
+  return last.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function collectPagesFromGroup(group: VeluGroup): string[] {
+  const pages: string[] = [];
+  for (const item of group.pages) {
+    if (typeof item === "string") pages.push(item);
+    else pages.push(...collectPagesFromGroup(item));
+  }
+  return pages;
+}
+
+function collectAllPages(config: VeluConfig): string[] {
+  const pages: string[] = [];
+  const nav = config.navigation;
+  if (nav.pages) pages.push(...nav.pages);
+  if (nav.groups) for (const g of nav.groups) pages.push(...collectPagesFromGroup(g));
+  if (nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.pages) pages.push(...tab.pages);
+      if (tab.groups) for (const g of tab.groups) pages.push(...collectPagesFromGroup(g));
+    }
+  }
+  return pages;
+}
+
+// ── Build ──────────────────────────────────────────────────────────────────────
+
+function build(docsDir: string, outDir: string) {
+  console.log(`📖 Loading velu.json from: ${docsDir}`);
+  const config = loadConfig(docsDir);
+
+  if (existsSync(outDir)) {
+    rmSync(outDir, { recursive: true, force: true });
+  }
+
+  // Create directories
+  mkdirSync(join(outDir, "src", "content", "docs"), { recursive: true });
+  mkdirSync(join(outDir, "src", "components"), { recursive: true });
+  mkdirSync(join(outDir, "src", "lib"), { recursive: true });
+  mkdirSync(join(outDir, "src", "styles"), { recursive: true });
+  mkdirSync(join(outDir, "public"), { recursive: true });
+
+  // ── 1. Copy velu.json into the Astro project ─────────────────────────────
+  copyFileSync(join(docsDir, "velu.json"), join(outDir, "velu.json"));
+  console.log("📋 Copied velu.json");
+
+  // ── 2. Copy all referenced .md files ──────────────────────────────────────
+  const allPages = collectAllPages(config);
+  for (const page of allPages) {
+    const srcPath = join(docsDir, `${page}.md`);
+    const destPath = join(outDir, "src", "content", "docs", `${page}.md`);
+
+    if (!existsSync(srcPath)) {
+      console.warn(`⚠️  Missing: ${srcPath}`);
+      continue;
+    }
+
+    mkdirSync(dirname(destPath), { recursive: true });
+
+    let content = readFileSync(srcPath, "utf-8");
+    if (!content.startsWith("---")) {
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(page);
+      if (titleMatch) {
+        content = content.replace(/^#\s+.+$/m, "").trimStart();
+      }
+      content = `---\ntitle: "${title}"\n---\n\n${content}`;
+    }
+
+    writeFileSync(destPath, content, "utf-8");
+  }
+  console.log(`📄 Copied ${allPages.length} pages`);
+
+  // ── 3. Generate src/lib/velu.ts — the single source of truth ──────────────
+  // This module reads velu.json at Astro build/render time. No hardcoded data.
+  const veluLib = `import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface VeluGroup {
+  group: string;
+  icon?: string;
+  tag?: string;
+  expanded?: boolean;
+  pages: (string | VeluGroup)[];
+}
+
+export interface VeluTab {
+  tab: string;
+  icon?: string;
+  href?: string;
+  pages?: string[];
+  groups?: VeluGroup[];
+}
+
+export interface VeluConfig {
+  $schema?: string;
+  navigation: {
+    tabs?: VeluTab[];
+    groups?: VeluGroup[];
+    pages?: string[];
+  };
+}
+
+export interface TabMeta {
+  label: string;
+  icon?: string;
+  href?: string;
+  pathPrefix: string;
+  firstPage?: string;
+}
+
+// ── Load config ─────────────────────────────────────────────────────────────
+
+let _cachedConfig: VeluConfig | null = null;
+
+export function loadVeluConfig(): VeluConfig {
+  if (_cachedConfig) return _cachedConfig;
+  const configPath = resolve(process.cwd(), 'velu.json');
+  const raw = readFileSync(configPath, 'utf-8');
+  _cachedConfig = JSON.parse(raw);
+  return _cachedConfig!;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function collectPagesFromGroup(group: VeluGroup): string[] {
+  const pages: string[] = [];
+  for (const item of group.pages) {
+    if (typeof item === 'string') pages.push(item);
+    else pages.push(...collectPagesFromGroup(item));
+  }
+  return pages;
+}
+
+function collectTabPages(tab: VeluTab): string[] {
+  const pages: string[] = [];
+  if (tab.pages) pages.push(...tab.pages);
+  if (tab.groups) for (const g of tab.groups) pages.push(...collectPagesFromGroup(g));
+  return pages;
+}
+
+function detectPathPrefix(slugs: string[]): string {
+  if (slugs.length === 0) return '';
+  const first = slugs[0];
+  const idx = first.indexOf('/');
+  if (idx === -1) return '';
+  const prefix = first.substring(0, idx);
+  if (slugs.every((s) => s.startsWith(prefix + '/'))) return prefix;
+  return '';
+}
+
+function veluGroupToSidebar(group: VeluGroup): any {
+  const items: any[] = [];
+  for (const item of group.pages) {
+    if (typeof item === 'string') items.push(item);
+    else items.push(veluGroupToSidebar(item));
+  }
+  const result: any = { label: group.group, items };
+  if (group.tag) result.badge = group.tag;
+  if (group.expanded === false) result.collapsed = true;
+  return result;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** Build the full Starlight sidebar array from velu.json */
+export function getSidebar(): any[] {
+  const config = loadVeluConfig();
+  const nav = config.navigation;
+  const sidebar: any[] = [];
+
+  // Default groups
+  if (nav.groups) {
+    for (const group of nav.groups) sidebar.push(veluGroupToSidebar(group));
+  }
+
+  // Default standalone pages
+  if (nav.pages) {
+    for (const page of nav.pages) sidebar.push(page);
+  }
+
+  // Tab content as top-level groups
+  if (nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.href) continue;
+      const items: any[] = [];
+      if (tab.groups) for (const g of tab.groups) items.push(veluGroupToSidebar(g));
+      if (tab.pages) for (const p of tab.pages) items.push(p);
+      sidebar.push({ label: tab.tab, items });
+    }
+  }
+
+  return sidebar;
+}
+
+/** Get tab metadata for the header navigation */
+export function getTabs(): TabMeta[] {
+  const config = loadVeluConfig();
+  const nav = config.navigation;
+  const tabs: TabMeta[] = [];
+
+  // Default "Docs" tab from groups/pages
+  const defaultPages: string[] = [];
+  if (nav.groups) for (const g of nav.groups) defaultPages.push(...collectPagesFromGroup(g));
+  if (nav.pages) defaultPages.push(...nav.pages);
+
+  if (defaultPages.length > 0) {
+    tabs.push({
+      label: 'Docs',
+      icon: 'book-open',
+      pathPrefix: detectPathPrefix(defaultPages) || '__default__',
+      firstPage: defaultPages[0],
+    });
+  }
+
+  if (nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.href) {
+        tabs.push({ label: tab.tab, icon: tab.icon, href: tab.href, pathPrefix: '' });
+      } else {
+        const tabPages = collectTabPages(tab);
+        tabs.push({
+          label: tab.tab,
+          icon: tab.icon,
+          pathPrefix: detectPathPrefix(tabPages) || tabPages[0]?.split('/')[0] || '',
+          firstPage: tabPages[0],
+        });
+      }
+    }
+  }
+
+  return tabs;
+}
+
+/** Get the mapping of path prefix → sidebar group labels for filtering */
+export function getTabSidebarMap(): Record<string, string[]> {
+  const config = loadVeluConfig();
+  const nav = config.navigation;
+  const map: Record<string, string[]> = {};
+
+  // Default tab owns top-level groups
+  const defaultLabels: string[] = [];
+  if (nav.groups) for (const g of nav.groups) defaultLabels.push(g.group);
+  map['__default__'] = defaultLabels;
+
+  if (nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.href) continue;
+      const tabPages = collectTabPages(tab);
+      const prefix = detectPathPrefix(tabPages) || tabPages[0]?.split('/')[0] || '';
+      map[prefix] = [tab.tab];
+    }
+  }
+
+  return map;
+}
+`;
+  writeFileSync(join(outDir, "src", "lib", "velu.ts"), veluLib, "utf-8");
+  console.log("📚 Generated config module");
+
+  // ── 4. Generate site config ────────────────────────────────────────────────
+  const astroConfig = `import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { getSidebar } from './src/lib/velu.ts';
+
+export default defineConfig({
+  devToolbar: { enabled: false },
+  integrations: [
+    starlight({
+      title: 'Velu Docs',
+      components: {
+        Header: './src/components/Header.astro',
+        Sidebar: './src/components/Sidebar.astro',
+      },
+      customCss: ['./src/styles/tabs.css'],
+      sidebar: getSidebar(),
+    }),
+  ],
+});
+`;
+  writeFileSync(join(outDir, "_config.mjs"), astroConfig, "utf-8");
+  console.log("⚙️  Generated site config");
+
+  // ── 5. Generate Header.astro — reads tabs from velu.ts ────────────────────
+  const headerComponent = `---
+import Default from '@astrojs/starlight/components/Header.astro';
+import { getTabs } from '../lib/velu.ts';
+
+const tabs = getTabs();
+const currentPath = Astro.url.pathname;
+
+function isTabActive(tab: any, path: string): boolean {
+  if (tab.href) return false;
+  if (tab.pathPrefix === '__default__') {
+    const otherPrefixes = tabs
+      .filter((t) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
+      .map((t) => t.pathPrefix);
+    return !otherPrefixes.some((p) => path.startsWith('/' + p + '/'));
+  }
+  return path.startsWith('/' + tab.pathPrefix + '/');
+}
+---
+
+<Default {...Astro.props}>
+  <slot />
+</Default>
+
+<nav class="velu-tabs">
+  <div class="velu-tabs-inner">
+    {tabs.map((tab) => {
+      if (tab.href) {
+        return (
+          <a href={tab.href} class="velu-tab" target="_blank" rel="noopener noreferrer">
+            {tab.label}
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7 17L17 7M17 7H7M17 7V17"/></svg>
+          </a>
+        );
+      }
+      const active = isTabActive(tab, currentPath);
+      const href = tab.firstPage ? '/' + tab.firstPage + '/' : '/';
+      return (
+        <a href={href} class:list={['velu-tab', { active }]}>
+          {tab.label}
+        </a>
+      );
+    })}
+  </div>
+</nav>
+`;
+  writeFileSync(join(outDir, "src", "components", "Header.astro"), headerComponent, "utf-8");
+  console.log("🧩 Generated header component");
+
+  // ── 6. Generate Sidebar.astro — reads filter map from velu.ts ─────────────
+  const sidebarComponent = `---
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import { getTabSidebarMap } from '../lib/velu.ts';
+
+const tabSidebarMap = getTabSidebarMap();
+const currentPath = Astro.url.pathname;
+
+function getActivePrefix(path: string): string {
+  const prefixes = Object.keys(tabSidebarMap).filter(p => p !== '__default__');
+  for (const prefix of prefixes) {
+    if (path.startsWith('/' + prefix + '/')) return prefix;
+  }
+  return '__default__';
+}
+
+const activePrefix = getActivePrefix(currentPath);
+const visibleLabels = new Set(tabSidebarMap[activePrefix] || []);
+
+const { sidebar } = Astro.locals.starlightRoute;
+const filteredSidebar = sidebar.filter((entry: any) => {
+  if (entry.type === 'group') return visibleLabels.has(entry.label);
+  return activePrefix === '__default__';
+});
+---
+
+<SidebarPersister>
+  <SidebarSublist sublist={filteredSidebar} />
+</SidebarPersister>
+
+<div class="md:sl-hidden">
+  <MobileMenuFooter />
+</div>
+`;
+  writeFileSync(join(outDir, "src", "components", "Sidebar.astro"), sidebarComponent, "utf-8");
+  console.log("📋 Generated sidebar component");
+
+  // ── 7. Generate tabs.css ──────────────────────────────────────────────────
+  const tabsCss = `/* ── Velu layout overrides ──────────────────────────────────────────────── */
+
+:root {
+  --sl-nav-height: 6rem;
+}
+
+/* Fixed header: flex column, no bottom padding — tab bar sits at the bottom */
+.page > header.header {
+  display: flex;
+  flex-direction: column;
+  padding-bottom: 0;
+}
+
+/* Standard nav content fills the top */
+.page > header.header > .header.sl-flex {
+  height: auto;
+  flex: 1;
+}
+
+/* ── Tab bar ───────────────────────────────────────────────────────────── */
+
+.velu-tabs {
+  flex-shrink: 0;
+  /* Stretch to full header width past its padding */
+  margin-inline: calc(-1 * var(--sl-nav-pad-x));
+  padding-inline: var(--sl-nav-pad-x);
+  background: var(--sl-color-bg-nav);
+}
+
+.velu-tabs-inner {
+  display: flex;
+  gap: 0.25rem;
+  overflow-x: auto;
+}
+
+.velu-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.55rem 0.85rem;
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  color: var(--sl-color-gray-3);
+  text-decoration: none;
+  border-radius: 0.375rem;
+  transition: color 0.15s, background-color 0.15s;
+  white-space: nowrap;
+}
+
+.velu-tab:hover {
+  color: var(--sl-color-gray-1);
+  background-color: var(--sl-color-gray-6);
+}
+
+.velu-tab.active {
+  color: var(--sl-color-white);
+  background-color: var(--sl-color-gray-5);
+}
+
+.velu-tab svg {
+  opacity: 0.5;
+  flex-shrink: 0;
+}
+`;
+  writeFileSync(join(outDir, "src", "styles", "tabs.css"), tabsCss, "utf-8");
+  console.log("🎨 Generated tabs.css");
+
+  // ── 8. Static boilerplate ─────────────────────────────────────────────────
+  const astroPkg = {
+    name: "velu-docs-site",
+    version: "0.0.1",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "astro dev",
+      build: "astro build",
+      preview: "astro preview",
+    },
+    dependencies: {
+      astro: "^5.1.0",
+      "@astrojs/starlight": "^0.32.0",
+      sharp: "^0.33.0",
+    },
+  };
+  writeFileSync(join(outDir, "package.json"), JSON.stringify(astroPkg, null, 2) + "\n", "utf-8");
+
+  writeFileSync(
+    join(outDir, "tsconfig.json"),
+    JSON.stringify({ extends: "astro/tsconfigs/strict" }, null, 2) + "\n",
+    "utf-8"
+  );
+
+  const firstPage = allPages[0] || "quickstart";
+  writeFileSync(
+    join(outDir, "src", "content", "docs", "index.mdx"),
+    `---\ntitle: "Welcome to Velu Docs"\ndescription: Documentation powered by Velu\n---\n\nWelcome to the documentation. Head over to the [Quickstart](/${firstPage}/) to get started.\n`,
+    "utf-8"
+  );
+
+  writeFileSync(
+    join(outDir, "src", "content.config.ts"),
+    `import { defineCollection } from 'astro:content';\nimport { docsSchema } from '@astrojs/starlight/schema';\n\nexport const collections = {\n  docs: defineCollection({ schema: docsSchema() }),\n};\n`,
+    "utf-8"
+  );
+
+  // ── 9. Generate _server.mjs — programmatic dev/build/preview ────────────────
+  const serverScript = `import { dev, build, preview } from 'astro';
+import { watch } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
+import { resolve, dirname, relative, extname, join } from 'node:path';
+
+// ── Docs directory (parent of .velu-out) ────────────────────────────────────
+const docsDir = resolve('..');
+const contentDir = resolve('src', 'content', 'docs');
+
+// ── Page processing (mirrors build.ts logic) ────────────────────────────────
+function pageLabelFromSlug(slug) {
+  const last = slug.split('/').pop() || slug;
+  return last.replace(/[-_]/g, ' ').replace(/\\b\\w/g, c => c.toUpperCase());
+}
+
+function processPage(srcPath, destPath, slug) {
+  let content = readFileSync(srcPath, 'utf-8');
+  if (!content.startsWith('---')) {
+    const titleMatch = content.match(/^#\\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
+    if (titleMatch) {
+      content = content.replace(/^#\\s+.+$/m, '').trimStart();
+    }
+    content = '---\\ntitle: "' + title + '"\\n---\\n\\n' + content;
+  }
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, content, 'utf-8');
+}
+
+function startWatcher() {
+  const debounce = new Map();
+
+  watch(docsDir, { recursive: true }, (eventType, filename) => {
+    if (!filename) return;
+    // Ignore changes inside .velu-out itself
+    if (filename.startsWith('.velu-out')) return;
+    // Ignore node_modules, hidden dirs
+    if (filename.includes('node_modules') || filename.startsWith('.')) return;
+
+    // Debounce — avoid duplicate events
+    if (debounce.has(filename)) clearTimeout(debounce.get(filename));
+    debounce.set(filename, setTimeout(() => {
+      debounce.delete(filename);
+      const srcPath = join(docsDir, filename);
+      if (!existsSync(srcPath)) return;
+
+      if (filename === 'velu.json') {
+        copyFileSync(srcPath, resolve('velu.json'));
+        console.log('  \\x1b[32m↻\\x1b[0m  velu.json updated');
+        return;
+      }
+
+      if (extname(filename) === '.md') {
+        const slug = filename.replace(/\\\\/g, '/').replace(/\\.md$/, '');
+        const destPath = join(contentDir, slug + '.md');
+        try {
+          processPage(srcPath, destPath, slug);
+          console.log('  \\x1b[32m↻\\x1b[0m  ' + slug);
+        } catch (e) {
+          console.error('  \\x1b[31m✗\\x1b[0m  Failed to sync ' + filename + ': ' + e.message);
+        }
+      }
+    }, 100));
+  });
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const command = args[0] || 'dev';
+const portIdx = args.indexOf('--port');
+const port = portIdx !== -1 ? parseInt(args[portIdx + 1]) : 4321;
+
+if (command === 'dev') {
+  const server = await dev({
+    root: '.',
+    configFile: './_config.mjs',
+    server: { port },
+    logLevel: 'silent',
+  });
+  const addr = server.address;
+  console.log('');
+  console.log('  \\x1b[36mvelu\\x1b[0m  v0.1.0  ready');
+  console.log('');
+  console.log('  ┃ Local    \\x1b[36mhttp://localhost:' + addr.port + '/\\x1b[0m');
+  console.log('  ┃ Network  use --host to expose');
+  console.log('');
+  console.log('  watching for file changes...');
+  startWatcher();
+} else if (command === 'build') {
+  console.log('\\n  Building site...\\n');
+  await build({ root: '.', configFile: './_config.mjs', logLevel: 'warn' });
+  console.log('\\n  ✅ Site built successfully.\\n');
+} else if (command === 'preview') {
+  const server = await preview({
+    root: '.',
+    configFile: './_config.mjs',
+    server: { port },
+    logLevel: 'silent',
+  });
+  const addr = server.address;
+  console.log('');
+  console.log('  \\x1b[36mvelu\\x1b[0m  preview');
+  console.log('');
+  console.log('  ┃ Local    \\x1b[36mhttp://localhost:' + addr.port + '/\\x1b[0m');
+  console.log('');
+}
+`;
+  writeFileSync(join(outDir, "_server.mjs"), serverScript, "utf-8");
+
+  // ── 10. Generate .gitignore ──────────────────────────────────────────────
+  writeFileSync(
+    join(outDir, ".gitignore"),
+    `.astro/\nnode_modules/\ndist/\n`,
+    "utf-8"
+  );
+
+  console.log("📦 Generated boilerplate");
+  console.log(`\n✅ Site generated at: ${outDir}`);
+}
+
+export { build };

package/src/cli.ts

@@ -0,0 +1,132 @@
+import { resolve, join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = resolve(dirname(__filename), "..");
+const SCHEMA_PATH = join(PACKAGE_ROOT, "schema", "velu.schema.json");
+
+// ── Help ────────────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+  velu — documentation site generator
+
+  Usage:
+    velu lint              Validate velu.json and check referenced pages
+    velu run [--port N]    Build site and start dev server (default: 4321)
+    velu build             Build site without starting the dev server
+
+  Options:
+    --port <number>   Port for the dev server (default: 4321)
+    --help            Show this help message
+
+  Run these commands from a directory containing velu.json.
+`);
+}
+
+// ── lint ─────────────────────────────────────────────────────────────────────────
+
+async function lint(docsDir: string) {
+  const { validateVeluConfig } = await import("./validate.js");
+  const result = validateVeluConfig(docsDir, SCHEMA_PATH);
+
+  if (result.valid) {
+    console.log("✅ velu.json is valid. All referenced pages exist.");
+  } else {
+    console.error("❌ Validation failed:\n");
+    for (const err of result.errors) {
+      console.error(`  • ${err}`);
+    }
+    process.exit(1);
+  }
+}
+
+// ── build ────────────────────────────────────────────────────────────────────────
+
+async function buildSite(docsDir: string): Promise<string> {
+  const { build } = await import("./build.js");
+  const outDir = join(docsDir, ".velu-out");
+  build(docsDir, outDir);
+  return outDir;
+}
+
+// ── run ──────────────────────────────────────────────────────────────────────────
+
+async function installDeps(outDir: string) {
+  if (!existsSync(join(outDir, "node_modules"))) {
+    console.log("\n📦 Installing dependencies...\n");
+    await new Promise<void>((res, rej) => {
+      const child = spawn("npm", ["install", "--silent"], {
+        cwd: outDir,
+        stdio: "inherit",
+        shell: true,
+      });
+      child.on("exit", (code) => (code === 0 ? res() : rej(new Error(`npm install exited with ${code}`))));
+    });
+  }
+}
+
+function spawnServer(outDir: string, command: string, port: number) {
+  const child = spawn("node", ["_server.mjs", command, "--port", String(port)], {
+    cwd: outDir,
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code) => process.exit(code ?? 0));
+
+  const cleanup = () => child.kill("SIGTERM");
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+async function run(docsDir: string, port: number) {
+  const outDir = await buildSite(docsDir);
+  await installDeps(outDir);
+  spawnServer(outDir, "dev", port);
+}
+
+// ── Parse args ───────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+const docsDir = process.cwd();
+
+if (!existsSync(join(docsDir, "velu.json"))) {
+  console.error("❌ No velu.json found in the current directory.");
+  console.error("   Run this command from a directory containing velu.json.");
+  process.exit(1);
+}
+
+switch (command) {
+  case "lint":
+    await lint(docsDir);
+    break;
+
+  case "build":
+    await buildSite(docsDir);
+    break;
+
+  case "run": {
+    const portIdx = args.indexOf("--port");
+    const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 4321;
+    if (isNaN(port)) {
+      console.error("❌ Invalid port number.");
+      process.exit(1);
+    }
+    await run(docsDir, port);
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    printHelp();
+    process.exit(1);
+}

package/src/validate.ts

@@ -0,0 +1,125 @@
+import Ajv, { type AnySchema } from "ajv";
+import addFormats from "ajv-formats";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+interface VeluGroup {
+  group: string;
+  icon?: string;
+  tag?: string;
+  expanded?: boolean;
+  pages: (string | VeluGroup)[];
+}
+
+interface VeluTab {
+  tab: string;
+  icon?: string;
+  href?: string;
+  pages?: string[];
+  groups?: VeluGroup[];
+}
+
+interface VeluConfig {
+  $schema?: string;
+  navigation: {
+    tabs?: VeluTab[];
+    groups?: VeluGroup[];
+    pages?: string[];
+  };
+}
+
+function loadJson(filePath: string): unknown {
+  const raw = readFileSync(filePath, "utf-8");
+  return JSON.parse(raw);
+}
+
+function collectPages(config: VeluConfig): string[] {
+  const pages: string[] = [];
+
+  function collectFromGroup(group: VeluGroup) {
+    for (const item of group.pages) {
+      if (typeof item === "string") {
+        pages.push(item);
+      } else {
+        collectFromGroup(item);
+      }
+    }
+  }
+
+  const nav = config.navigation;
+
+  if (nav.pages) {
+    pages.push(...nav.pages);
+  }
+
+  if (nav.groups) {
+    for (const group of nav.groups) {
+      collectFromGroup(group);
+    }
+  }
+
+  if (nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.pages) {
+        pages.push(...tab.pages);
+      }
+      if (tab.groups) {
+        for (const group of tab.groups) {
+          collectFromGroup(group);
+        }
+      }
+    }
+  }
+
+  return pages;
+}
+
+function validateVeluConfig(docsDir: string, schemaPath: string): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  const configPath = join(docsDir, "velu.json");
+  if (!existsSync(configPath)) {
+    return { valid: false, errors: [`velu.json not found at ${configPath}`] };
+  }
+
+  if (!existsSync(schemaPath)) {
+    return { valid: false, errors: [`Schema not found at ${schemaPath}`] };
+  }
+
+  const schema = loadJson(schemaPath) as AnySchema;
+  const config = loadJson(configPath) as VeluConfig;
+
+  // Validate against JSON schema
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  const schemaValid = validate(config);
+
+  if (!schemaValid && validate.errors) {
+    for (const err of validate.errors) {
+      errors.push(`Schema: ${err.instancePath || "/"} ${err.message}`);
+    }
+  }
+
+  // Validate that all referenced .md files exist
+  const pages = collectPages(config);
+  for (const page of pages) {
+    const mdPath = join(docsDir, `${page}.md`);
+    if (!existsSync(mdPath)) {
+      errors.push(`Missing page: ${page}.md (expected at ${mdPath})`);
+    }
+  }
+
+  // Check for duplicate page references
+  const seen = new Set<string>();
+  for (const page of pages) {
+    if (seen.has(page)) {
+      errors.push(`Duplicate page reference: ${page}`);
+    }
+    seen.add(page);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export { validateVeluConfig, collectPages, VeluConfig, VeluGroup, VeluTab };