@litodocs/cli 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lito docs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# Lito
+
+Beautiful documentation sites from Markdown. Fast, simple, and open-source.
+
+## Features
+
+✨ **Simple Setup** - Point to your docs folder and go 
+🚀 **Astro-Powered** - Leverages Astro's speed and SEO optimization
+📝 **Markdown & MDX** - Full support for both formats with frontmatter
+🎨 **Customizable Templates** - Use GitHub-hosted or local templates
+🔥 **Hot Reload** - Dev server with live file watching
+⚡ **Fast Builds** - Static site generation for optimal performance
+🎯 **SEO Optimized** - Meta tags, semantic HTML, and proper structure
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g @litodocs/cli
+# or
+pnpm add -g @litodocs/cli
+```
+
+### Local Development
+
+```bash
+cd lito
+pnpm install
+chmod +x bin/cli.js
+```
+
+## Usage
+
+### Build Command
+
+Generate a static documentation site:
+
+```bash
+lito build --input ./my-docs --output ./dist
+```
+
+**Options:**
+
+- `-i, --input <path>` (required) - Path to your docs folder
+- `-o, --output <path>` - Output directory (default: `./dist`)
+- `-t, --template <name>` - Template to use (see [Templates](#templates))
+- `-b, --base-url <url>` - Base URL for the site (default: `/`)
+- `--provider <name>` - optimize for hosting provider (vercel, netlify, cloudflare, static)
+- `--rendering <mode>` - Rendering mode (static, server, hybrid)
+- `--search` - Enable search functionality
+- `--refresh` - Force re-download template from GitHub
+
+### Dev Command
+
+Start a development server with hot reload:
+
+```bash
+lito dev --input ./my-docs
+```
+
+**Options:**
+
+- `-i, --input <path>` (required) - Path to your docs folder
+- `-t, --template <name>` - Template to use
+- `-b, --base-url <url>` - Base URL for the site
+- `-p, --port <number>` - Port for dev server (default: `4321`)
+- `--search` - Enable search functionality
+- `--refresh` - Force re-download template
+
+### Eject Command
+
+Export the full Astro project source code to customize it further:
+
+```bash
+lito eject --input ./my-docs --output ./my-project
+```
+
+## Deployment
+
+Lito includes built-in optimizations for major hosting providers. Use the `--provider` flag during build:
+
+### Vercel
+```bash
+lito build -i ./docs --provider vercel
+```
+Generates `vercel.json` and optimizes for Vercel's edge network.
+
+### Netlify
+```bash
+lito build -i ./docs --provider netlify
+```
+Generates `netlify.toml` with security headers.
+
+### Cloudflare Pages
+```bash
+lito build -i ./docs --provider cloudflare --rendering server
+```
+Configures the project for Cloudflare's edge runtime with SSR support.
+
+## Analytics
+
+Lito supports Google Analytics 4 out of the box with zero performance penalty (powered by Partytown).
+
+Add this to your `docs-config.json`:
+
+```json
+{
+  "integrations": {
+    "analytics": {
+      "provider": "google-analytics",
+      "measurementId": "G-XXXXXXXXXX"
+    }
+  }
+}
+```
+
+## Templates
+
+Lito supports flexible template sources:
+
+### Default Template
+
+```bash
+lito dev -i ./docs
+```
+
+### GitHub Templates
+
+Use templates hosted on GitHub:
+
+```bash
+# From a GitHub repo
+lito dev -i ./docs --template github:owner/repo
+
+# Specific branch or tag
+lito dev -i ./docs --template github:owner/repo#v1.0.0
+
+# Template in a subdirectory
+lito dev -i ./docs --template github:owner/repo/templates/modern
+```
+
+### Local Templates
+
+Use a local template folder:
+
+```bash
+lito dev -i ./docs --template ./my-custom-template
+```
+
+### Template Management
+
+```bash
+# List available templates
+lito template list
+
+# Clear template cache
+lito template cache --clear
+```
+
+### Update Templates
+
+Templates are cached for 24 hours. Force update with:
+
+```bash
+lito dev -i ./docs --refresh
+```
+
+## Documentation Structure
+
+Your docs folder should contain Markdown (`.md`) or MDX (`.mdx`) files:
+
+```
+my-docs/
+├── index.md
+├── getting-started.md
+├── api/
+│   ├── reference.md
+│   └── examples.md
+└── guides/
+    └── advanced.md
+```
+
+### Frontmatter
+
+Add frontmatter to your markdown files for better metadata:
+
+```markdown
+---
+title: Getting Started
+description: Learn how to get started quickly
+---
+
+# Getting Started
+
+Your content here...
+```
+
+## Architecture
+
+The CLI tool:
+
+1. **Resolves Template** - Fetches from GitHub or uses local template
+2. **Scaffolds** - Creates a temporary Astro project from the template
+3. **Syncs** - Copies your docs into `src/pages/` for automatic routing
+4. **Configures** - Generates dynamic `astro.config.mjs` with your options
+5. **Builds/Serves** - Spawns native Astro CLI commands
+6. **Watches** (dev mode) - Uses `chokidar` to monitor file changes
+
+## Development
+
+### Project Structure
+
+```
+lito/
+├── bin/
+│   └── cli.js              # CLI entry point
+├── src/
+│   ├── cli.js              # Commander setup
+│   ├── commands/
+│   │   ├── build.js        # Build command
+│   │   ├── dev.js          # Dev command with watcher
+│   │   ├── eject.js        # Eject command
+│   │   └── template.js     # Template management
+│   ├── core/
+│   │   ├── scaffold.js     # Project scaffolding
+│   │   ├── sync.js         # File syncing
+│   │   ├── config.js       # Config generation
+│   │   ├── astro.js        # Astro CLI spawning
+│   │   ├── template-fetcher.js   # GitHub template fetching
+│   │   └── template-registry.js  # Template name registry
+│   └── template/           # Bundled fallback template
+└── package.json
+```
+
+### Running Tests
+
+```bash
+# Create sample docs
+mkdir sample-docs
+echo "# Hello\n\nWelcome!" > sample-docs/index.md
+
+# Test build
+node bin/cli.js build -i sample-docs -o test-output
+
+# Test dev server
+node bin/cli.js dev -i sample-docs
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+---
+
+**Built with ❤️ using Astro and Node.js**

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import('../src/cli.js')
+  .then(({ cli }) => cli())
+  .catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@litodocs/cli",
+  "version": "0.5.0",
+  "description": "Beautiful documentation sites from Markdown. Fast, simple, and open-source.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "lito": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lito-docs/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Lito-docs/cli/issues"
+  },
+  "homepage": "https://github.com/Lito-docs/cli#readme",
+  "keywords": [
+    "documentation",
+    "docs",
+    "markdown",
+    "mdx",
+    "astro",
+    "static-site-generator",
+    "documentation-generator",
+    "lito",
+    "open-source"
+  ],
+  "author": "Lito-docs",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^3.1.0",
+    "@clack/prompts": "^0.11.0",
+    "astro": "^4.16.0",
+    "chokidar": "^4.0.0",
+    "commander": "^12.1.0",
+    "execa": "^9.0.0",
+    "fs-extra": "^11.2.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,116 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { buildCommand } from "./commands/build.js";
+import { devCommand } from "./commands/dev.js";
+import { ejectCommand } from "./commands/eject.js";
+import {
+  templateListCommand,
+  templateCacheCommand,
+} from "./commands/template.js";
+
+export async function cli() {
+  const program = new Command();
+
+  program
+    .name("lito")
+    .description(
+      "Beautiful documentation sites from Markdown. Fast, simple, and open-source."
+    )
+    .version("0.5.0");
+
+  program
+    .command("build")
+    .description("Build the documentation site")
+    .requiredOption("-i, --input <path>", "Path to the docs folder")
+    .option(
+      "-o, --output <path>",
+      "Output directory for the built site",
+      "./dist"
+    )
+    .option(
+      "-t, --template <name>",
+      "Template to use (default, github:owner/repo, or local path)",
+      "default"
+    )
+    .option("-b, --base-url <url>", "Base URL for the site", "/")
+    .option("--name <name>", "Project name")
+    .option("--description <description>", "Project description")
+    .option("--primary-color <color>", "Primary theme color (hex)")
+    .option("--accent-color <color>", "Accent theme color (hex)")
+    .option("--favicon <path>", "Favicon path")
+    .option("--logo <path>", "Logo path")
+    .option("--provider <name>", "Hosting provider optimization (vercel, netlify, cloudflare, static)", "static")
+    .option("--rendering <type>", "Rendering mode (static, server, hybrid)", "static")
+    .option("--search", "Enable search functionality", false)
+    .option("--refresh", "Force re-download template (bypass cache)", false)
+    .action(buildCommand);
+
+  program
+    .command("dev")
+    .description("Start development server with watch mode")
+    .requiredOption("-i, --input <path>", "Path to the docs folder")
+    .option(
+      "-t, --template <name>",
+      "Template to use (default, github:owner/repo, or local path)",
+      "default"
+    )
+    .option("-b, --base-url <url>", "Base URL for the site", "/")
+    .option("--name <name>", "Project name")
+    .option("--description <description>", "Project description")
+    .option("--primary-color <color>", "Primary theme color (hex)")
+    .option("--accent-color <color>", "Accent theme color (hex)")
+    .option("--favicon <path>", "Favicon path")
+    .option("--logo <path>", "Logo path")
+    .option("--search", "Enable search functionality", false)
+    .option("-p, --port <number>", "Port for dev server", "4321")
+    .option("--refresh", "Force re-download template (bypass cache)", false)
+    .action(devCommand);
+
+  program
+    .command("eject")
+    .description("Export the full Astro project source code")
+    .requiredOption("-i, --input <path>", "Path to the docs folder")
+    .option(
+      "-o, --output <path>",
+      "Output directory for the project",
+      "./astro-docs-project"
+    )
+    .option(
+      "-t, --template <name>",
+      "Template to use (default, github:owner/repo, or local path)",
+      "default"
+    )
+    .option("-b, --base-url <url>", "Base URL for the site", "/")
+    .option("--name <name>", "Project name")
+    .option("--description <description>", "Project description")
+    .option("--primary-color <color>", "Primary theme color (hex)")
+    .option("--accent-color <color>", "Accent theme color (hex)")
+    .option("--favicon <path>", "Favicon path")
+    .option("--logo <path>", "Logo path")
+    .option("--search", "Enable search functionality", false)
+    .option("--refresh", "Force re-download template (bypass cache)", false)
+    .action(ejectCommand);
+
+  // Template management commands
+  const templateCmd = program
+    .command("template")
+    .description("Manage documentation templates");
+
+  templateCmd
+    .command("list")
+    .description("List available templates")
+    .action(templateListCommand);
+
+  templateCmd
+    .command("cache")
+    .description("Manage template cache")
+    .option("--clear", "Clear all cached templates")
+    .action(templateCacheCommand);
+
+  try {
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    console.error(pc.red("Error:"), error.message);
+    process.exit(1);
+  }
+}

package/src/commands/build.js

@@ -0,0 +1,105 @@
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { intro, outro, spinner, log, isCancel, cancel } from '@clack/prompts';
+import pc from 'picocolors';
+import { scaffoldProject, cleanupProject } from '../core/scaffold.js';
+import { syncDocs } from '../core/sync.js';
+import { generateConfig } from '../core/config.js';
+import { runAstroBuild } from '../core/astro.js';
+import { syncDocsConfig } from '../core/config-sync.js';
+import { copyOutput } from '../core/output.js';
+import { getTemplatePath } from '../core/template-fetcher.js';
+
+export async function buildCommand(options) {
+  try {
+    // Validate input path
+    const inputPath = resolve(options.input);
+    if (!existsSync(inputPath)) {
+      log.error(`Input path does not exist: ${pc.cyan(inputPath)}`);
+      process.exit(1);
+    }
+
+    console.clear();
+    intro(pc.inverse(pc.cyan(' Lito - Build ')));
+
+    const s = spinner();
+
+    // Step 0: Resolve template
+    s.start('Resolving template...');
+    const templatePath = await getTemplatePath(options.template, options.refresh);
+    s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
+
+    // Step 1: Scaffold temporary Astro project
+    s.start('Setting up Astro project...');
+    const projectDir = await scaffoldProject(templatePath);
+    s.stop('Astro project scaffolded');
+
+    // Step 2: Prepare project (Install dependencies, Sync docs, Generate navigation)
+    const { installDependencies, runBinary } = await import('../core/package-manager.js');
+    s.start('Preparing project (installing dependencies, syncing files)...');
+    
+    const userConfigPath = resolve(options.input, 'docs-config.json');
+
+    await Promise.all([
+      installDependencies(projectDir, { silent: true }),
+      syncDocs(inputPath, projectDir),
+      syncDocsConfig(projectDir, inputPath, userConfigPath)
+    ]);
+
+    s.stop('Project prepared (dependencies installed, docs synced, navigation generated)');
+
+    // Step 4: Generate config
+    s.start('Generating Astro configuration...');
+    await generateConfig(projectDir, options);
+    s.stop('Configuration generated');
+
+    // Step 4.5: Configure for provider
+    if (options.provider && options.provider !== 'static') {
+      s.start(`Configuring for ${options.provider} (${options.rendering})...`);
+      const { configureProvider } = await import('../core/providers.js');
+      await configureProvider(projectDir, options.provider, options.rendering);
+      s.stop(`Configured for ${options.provider}`);
+    }
+
+    // Step 5: Build with Astro
+    s.start('Building site with Astro...');
+    await runAstroBuild(projectDir);
+    s.stop('Site built successfully');
+
+    // Step 5.5: Generate Pagefind search index
+    s.start('Generating search index...');
+    await runBinary(projectDir, 'pagefind', ['--site', 'dist']);
+    s.stop('Search index generated');
+
+    // Step 6: Copy output
+    const outputPath = resolve(options.output);
+    s.start(`Copying output to ${pc.cyan(outputPath)}...`);
+    await copyOutput(projectDir, outputPath);
+    s.stop('Output copied');
+
+    // Cleanup temp directory
+    s.start('Cleaning up...');
+    await cleanupProject();
+    s.stop('Cleanup complete');
+
+    outro(pc.green('Build completed successfully!'));
+  } catch (error) {
+    if (isCancel(error)) {
+      cancel('Operation cancelled.');
+      process.exit(0);
+    }
+
+    // Attempt to cleanup even on error
+    try {
+      await cleanupProject();
+    } catch (e) {
+      // failed to cleanup
+    }
+
+    log.error(pc.red(error.message));
+    if (error.stack) {
+      log.error(pc.gray(error.stack));
+    }
+    process.exit(1);
+  }
+}

package/src/commands/dev.js

@@ -0,0 +1,133 @@
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { intro, outro, spinner, log, note, isCancel, cancel } from '@clack/prompts';
+import pc from 'picocolors';
+import chokidar from 'chokidar';
+import { scaffoldProject, cleanupProject } from '../core/scaffold.js';
+import { syncDocs } from '../core/sync.js';
+import { generateConfig } from '../core/config.js';
+import { runAstroDev } from '../core/astro.js';
+import { syncDocsConfig } from '../core/config-sync.js';
+import { getTemplatePath } from '../core/template-fetcher.js';
+
+export async function devCommand(options) {
+  try {
+    // Validate input path
+    const inputPath = resolve(options.input);
+    if (!existsSync(inputPath)) {
+      log.error(`Input path does not exist: ${pc.cyan(inputPath)}`);
+      process.exit(1);
+    }
+
+    console.clear();
+    intro(pc.inverse(pc.cyan(' Lito - Dev Server ')));
+
+    const s = spinner();
+
+    // Step 0: Resolve template
+    s.start('Resolving template...');
+    const templatePath = await getTemplatePath(options.template, options.refresh);
+    s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
+
+    // Step 1: Scaffold temporary Astro project
+    s.start('Setting up Astro project...');
+    const projectDir = await scaffoldProject(templatePath);
+    s.stop('Astro project scaffolded');
+
+    // Register cleanup handlers
+    const cleanup = async () => {
+      s.start('Cleaning up...');
+      await cleanupProject();
+      s.stop('Cleanup complete');
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+
+    // Step 2: Prepare project (Install dependencies, Sync docs, Generate navigation)
+    const { installDependencies } = await import('../core/package-manager.js');
+    s.start('Preparing project (installing dependencies, syncing files)...');
+
+    const userConfigPath = resolve(options.input, 'docs-config.json');
+
+    await Promise.all([
+      installDependencies(projectDir, { silent: true }),
+      syncDocs(inputPath, projectDir),
+      syncDocsConfig(projectDir, inputPath, userConfigPath)
+    ]);
+
+    s.stop('Project prepared (dependencies installed, docs synced, navigation generated)');
+
+    // Step 4: Generate config
+    s.start('Generating Astro configuration...');
+    await generateConfig(projectDir, options);
+    s.stop('Configuration generated');
+
+    // Step 4: Setup file watcher with debouncing
+    log.info(pc.cyan('Watching for file changes...'));
+
+    let syncTimeout = null;
+    let isSyncing = false;
+
+    const debouncedSync = async () => {
+      if (isSyncing) return;
+
+      if (syncTimeout) {
+        clearTimeout(syncTimeout);
+      }
+
+      syncTimeout = setTimeout(async () => {
+        if (isSyncing) return;
+        isSyncing = true;
+
+        try {
+          await Promise.all([
+            syncDocs(inputPath, projectDir),
+            syncDocsConfig(projectDir, inputPath, userConfigPath)
+          ]);
+          log.success('Documentation and config re-synced');
+        } catch (error) {
+          log.error('Sync failed: ' + error.message);
+        } finally {
+          isSyncing = false;
+        }
+      }, 300); // 300ms debounce
+    };
+
+    const watcher = chokidar.watch(inputPath, {
+      ignored: /(^|[\/\\])\../,
+      persistent: true,
+      ignoreInitial: true, // Don't trigger for existing files
+    });
+
+    watcher.on('change', async (path) => {
+      log.info(`File changed: ${pc.dim(path)}`);
+      debouncedSync();
+    });
+
+    watcher.on('add', async (path) => {
+      log.success(`File added: ${pc.dim(path)}`);
+      debouncedSync();
+    });
+
+    watcher.on('unlink', async (path) => {
+      log.warning(`File removed: ${pc.dim(path)}`);
+      debouncedSync();
+    });
+
+    // Step 5: Start Astro dev server
+    note(`Starting Astro dev server at http://localhost:${options.port}`, 'Dev Server');
+    await runAstroDev(projectDir, options.port);
+
+  } catch (error) {
+    if (isCancel(error)) {
+      cancel('Operation cancelled.');
+      process.exit(0);
+    }
+    log.error(pc.red('Dev server failed: ' + error.message));
+    if (error.stack) {
+      log.error(pc.gray(error.stack));
+    }
+    process.exit(1);
+  }
+}