@litodocs/cli 0.6.0 → 0.7.0

package/README.md

@@ -2,25 +2,27 @@
 
 Beautiful documentation sites from Markdown. Fast, simple, and open-source.
 
+[![npm version](https://img.shields.io/npm/v/@litodocs/cli)](https://www.npmjs.com/package/@litodocs/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
 > **Note:** This package was previously published as `@devrohit06/superdocs`. It has been renamed to `@litodocs/cli`.
 
 ## 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
-- 🌍 **i18n Support** - Built-in internationalization with 40+ languages
-- 📚 **Versioning** - Documentation versioning with version switcher
-- 🎨 **Dynamic Theming** - OKLCH color palette generation from primary color
+- **Multi-Framework** - Choose your preferred framework: Astro, React, Next.js, Vue, or Nuxt
+- **Simple Setup** - Point to your docs folder and go
+- **Markdown & MDX** - Full support for both formats with frontmatter
+- **Custom Landing Pages** - Full HTML/CSS/JS control or section-based layouts
+- **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
+- **i18n Support** - Built-in internationalization with 40+ languages
+- **Versioning** - Documentation versioning with version switcher
+- **Dynamic Theming** - OKLCH color palette generation from primary color
+- **GitHub Templates** - Use official or custom GitHub-hosted templates
 
 ## Installation
 
-### Global Installation
-
 ```bash
 npm install -g @litodocs/cli
 # or
@@ -29,203 +31,407 @@ pnpm add -g @litodocs/cli
 yarn global add @litodocs/cli
 ```
 
-### Local Development
+## Quick Start
 
-Clone the repository and link it locally:
+```bash
+# Initialize a new docs project
+lito init
+
+# Start dev server
+lito dev -i ./my-docs
+
+# Build for production
+lito build -i ./my-docs -o ./dist
+
+# Preview production build
+lito preview -o ./dist
+```
+
+## Commands
+
+| Command         | Description                                  |
+| --------------- | -------------------------------------------- |
+| `lito init`     | Initialize a new documentation project       |
+| `lito dev`      | Start development server with hot reload     |
+| `lito build`    | Generate static documentation site           |
+| `lito preview`  | Preview production build locally             |
+| `lito validate` | Validate docs-config.json configuration      |
+| `lito doctor`   | Diagnose common issues                       |
+| `lito info`     | Show project information and statistics      |
+| `lito eject`    | Export full project source for customization |
+| `lito template` | Manage templates (list, cache)               |
+| `lito upgrade`  | Update CLI to latest version                 |
+
+## Multi-Framework Support
+
+Lito supports multiple frameworks. Choose the one that fits your workflow:
 
 ```bash
-git clone https://github.com/Lito-docs/cli.git
-cd cli
-pnpm install
-chmod +x bin/cli.js
-npm link
+# Astro (default) - Fast static sites
+lito dev -i ./docs --template astro
+
+# React - Vite-powered React app
+lito dev -i ./docs --template react
+
+# Next.js - React with SSR/SSG
+lito dev -i ./docs --template next
+
+# Vue - Vite-powered Vue app
+lito dev -i ./docs --template vue
+
+# Nuxt - Vue with SSR/SSG
+lito dev -i ./docs --template nuxt
 ```
 
-Now you can use `lito` command globally from your terminal.
+### Template Registry
 
-## Quick Start
+| Shorthand | Repository                             |
+| --------- | -------------------------------------- |
+| `astro`   | `github:Lito-docs/lito-astro-template` |
+| `react`   | `github:Lito-docs/lito-react-template` |
+| `next`    | `github:Lito-docs/lito-next-template`  |
+| `vue`     | `github:Lito-docs/lito-vue-template`   |
+| `nuxt`    | `github:Lito-docs/lito-nuxt-template`  |
+
+You can also use custom templates:
 
 ```bash
-# Create a docs folder with markdown files
-mkdir my-docs
-echo "# Hello World" > my-docs/index.md
+# GitHub repository
+lito dev -i ./docs --template github:owner/repo
 
-# Start dev server
+# Specific branch or tag
+lito dev -i ./docs --template github:owner/repo#v1.0.0
+
+# Local template
+lito dev -i ./docs --template ./my-custom-template
+```
+
+## Command Reference
+
+### `lito init`
+
+Initialize a new documentation project with interactive prompts:
+
+```bash
+lito init
+lito init -o ./my-docs -n "My Project" --template react
+```
+
+| Option                  | Description         | Default       |
+| ----------------------- | ------------------- | ------------- |
+| `-o, --output <path>`   | Output directory    | (interactive) |
+| `-n, --name <name>`     | Project name        | (interactive) |
+| `-t, --template <name>` | Template to use     | `astro`       |
+| `--sample`              | Create sample pages | `true`        |
+
+### `lito dev`
+
+Start development server with hot reload:
+
+```bash
 lito dev -i ./my-docs
+lito dev -i ./my-docs --template react --port 3000
+```
 
-# Build for production
+| Option                  | Description                    | Default |
+| ----------------------- | ------------------------------ | ------- |
+| `-i, --input <path>`    | Path to docs folder (required) | -       |
+| `-t, --template <name>` | Template to use                | `astro` |
+| `-p, --port <number>`   | Dev server port                | `4321`  |
+| `-b, --base-url <url>`  | Base URL for the site          | `/`     |
+| `--search`              | Enable search                  | `false` |
+| `--refresh`             | Force re-download template     | `false` |
+
+### `lito build`
+
+Generate a static documentation site:
+
+```bash
 lito build -i ./my-docs -o ./dist
+lito build -i ./my-docs --provider vercel --template next
 ```
 
-## Usage
+| Option                  | Description                                            | Default  |
+| ----------------------- | ------------------------------------------------------ | -------- |
+| `-i, --input <path>`    | Path to docs folder (required)                         | -        |
+| `-o, --output <path>`   | Output directory                                       | `./dist` |
+| `-t, --template <name>` | Template to use                                        | `astro`  |
+| `-b, --base-url <url>`  | Base URL for the site                                  | `/`      |
+| `--provider <name>`     | Hosting provider (vercel, netlify, cloudflare, static) | `static` |
+| `--rendering <mode>`    | Rendering mode (static, server, hybrid)                | `static` |
+| `--search`              | Enable search                                          | `false`  |
+| `--refresh`             | Force re-download template                             | `false`  |
 
-### Build Command
+### `lito preview`
 
-Generate a static documentation site:
+Preview production build locally:
 
 ```bash
-lito build --input ./my-docs --output ./dist
+lito preview -o ./dist
+lito preview -i ./my-docs  # Auto-builds if needed
 ```
 
-**Options:**
+| Option                | Description                         | Default  |
+| --------------------- | ----------------------------------- | -------- |
+| `-i, --input <path>`  | Docs folder (will build if no dist) | -        |
+| `-o, --output <path>` | Path to built site                  | `./dist` |
+| `-p, --port <number>` | Preview server port                 | `4321`   |
+
+### `lito validate`
+
+Validate your configuration:
+
+```bash
+lito validate -i ./my-docs
+lito validate -i ./my-docs --quiet  # For CI pipelines
+```
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-i, --input <path>` | Path to your docs folder (required) | - |
-| `-o, --output <path>` | Output directory | `./dist` |
-| `-t, --template <name>` | Template to use | `default` |
-| `-b, --base-url <url>` | Base URL for the site | `/` |
-| `--provider <name>` | Hosting provider (vercel, netlify, cloudflare, static) | `static` |
-| `--rendering <mode>` | Rendering mode (static, server, hybrid) | `static` |
-| `--search` | Enable search functionality | `false` |
-| `--refresh` | Force re-download template | `false` |
+| Option               | Description             | Default |
+| -------------------- | ----------------------- | ------- |
+| `-i, --input <path>` | Path to docs folder     | `.`     |
+| `-q, --quiet`        | Exit code only (for CI) | `false` |
 
-### Dev Command
+### `lito doctor`
 
-Start a development server with hot reload:
+Diagnose common issues:
 
 ```bash
-lito dev --input ./my-docs
+lito doctor -i ./my-docs
 ```
 
-**Options:**
+Checks performed:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-i, --input <path>` | Path to your docs folder (required) | - |
-| `-t, --template <name>` | Template to use | `default` |
-| `-b, --base-url <url>` | Base URL for the site | `/` |
-| `-p, --port <number>` | Port for dev server | `4321` |
-| `--search` | Enable search functionality | `false` |
-| `--refresh` | Force re-download template | `false` |
+- Directory and config file existence
+- JSON syntax and schema validation
+- Content files (.md/.mdx) presence
+- Common mistakes (misplaced files)
+- Template cache status
+- Node.js version (18+ required, 20+ recommended)
 
-### Eject Command
+### `lito info`
 
-Export the full Astro project source code to customize it further:
+Show project information:
 
 ```bash
-lito eject --input ./my-docs --output ./my-project
+lito info -i ./my-docs
 ```
 
-## Deployment
+Displays:
 
-Lito includes built-in optimizations for major hosting providers. Use the `--provider` flag during build:
+- Project metadata
+- Content statistics
+- Navigation structure
+- Enabled features
+- Branding configuration
+- Environment info
 
-### Vercel
+### `lito eject`
+
+Export the full project source:
 
 ```bash
-lito build -i ./docs --provider vercel
+lito eject -i ./my-docs -o ./my-project
 ```
 
-Generates `vercel.json` and optimizes for Vercel's edge network.
+### `lito template`
 
-### Netlify
+Manage templates:
 
 ```bash
-lito build -i ./docs --provider netlify
+lito template list          # List available templates
+lito template cache --clear # Clear template cache
 ```
 
-Generates `netlify.toml` with security headers.
+### `lito upgrade`
 
-### Cloudflare Pages
+Update to latest version:
 
 ```bash
-lito build -i ./docs --provider cloudflare --rendering server
+lito upgrade
 ```
 
-Configures the project for Cloudflare's edge runtime with SSR support.
+## Custom Landing Pages
 
-## Analytics
+### Full Custom Landing
+
+Create a `_landing/` folder with HTML/CSS/JS:
 
-Lito supports Google Analytics 4 out of the box with zero performance penalty (powered by Partytown).
+```
+my-docs/
+├── _landing/
+│   ├── index.html
+│   ├── styles.css
+│   └── script.js
+├── introduction.mdx
+└── docs-config.json
+```
 
-Add this to your `docs-config.json`:
+Configure in `docs-config.json`:
 
 ```json
 {
-  "integrations": {
-    "analytics": {
-      "provider": "google-analytics",
-      "measurementId": "G-XXXXXXXXXX"
-    }
+  "landing": {
+    "type": "custom",
+    "source": "_landing",
+    "injectNav": true,
+    "injectFooter": true
   }
 }
 ```
 
-## Templates
-
-Lito supports flexible template sources:
+### Section-Based Landing
 
-### Default Template
+Mix custom HTML with default components:
 
-```bash
-lito dev -i ./docs
+```json
+{
+  "landing": {
+    "type": "sections",
+    "sections": [
+      { "type": "hero", "source": "default" },
+      { "type": "custom", "html": "_landing/features.html" },
+      { "type": "cta", "source": "default" },
+      { "type": "custom", "html": "_landing/pricing.html" }
+    ]
+  }
+}
 ```
 
-### GitHub Templates
+### Available Section Types
+
+| Section        | Description                         |
+| -------------- | ----------------------------------- |
+| `hero`         | Main hero with title, subtitle, CTA |
+| `features`     | Feature grid or list                |
+| `cta`          | Call-to-action banner               |
+| `testimonials` | Customer testimonials               |
+| `pricing`      | Pricing tables                      |
+| `faq`          | Frequently asked questions          |
+| `stats`        | Statistics/metrics                  |
+| `logos`        | Partner/client logos                |
+| `comparison`   | Feature comparison table            |
+| `footer`       | Custom footer section               |
+
+### Landing Types
+
+| Type       | Description                        |
+| ---------- | ---------------------------------- |
+| `none`     | No landing, go straight to docs    |
+| `default`  | Use template's default landing     |
+| `config`   | Generate from docs-config.json     |
+| `custom`   | Full HTML/CSS/JS from `_landing/`  |
+| `sections` | Mix of custom and default sections |
 
-Use templates hosted on GitHub:
+## Deployment
+
+### Vercel
 
 ```bash
-# From a GitHub repo
-lito dev -i ./docs --template github:owner/repo
+lito build -i ./docs --provider vercel
+```
 
-# Specific branch or tag
-lito dev -i ./docs --template github:owner/repo#v1.0.0
+### Netlify
 
-# Template in a subdirectory
-lito dev -i ./docs --template github:owner/repo/templates/modern
+```bash
+lito build -i ./docs --provider netlify
 ```
 
-### Local Templates
-
-Use a local template folder:
+### Cloudflare Pages
 
 ```bash
-lito dev -i ./docs --template ./my-custom-template
+lito build -i ./docs --provider cloudflare --rendering server
 ```
 
-### Template Management
+## Configuration
 
-```bash
-# List available templates
-lito template list
+Create a `docs-config.json` in your docs folder:
 
-# Clear template cache
-lito template cache --clear
+```json
+{
+  "metadata": {
+    "name": "My Docs",
+    "description": "Documentation for my project"
+  },
+  "branding": {
+    "primaryColor": "#10b981",
+    "logo": "/logo.svg",
+    "favicon": "/favicon.ico"
+  },
+  "navigation": {
+    "sidebar": [
+      {
+        "group": "Getting Started",
+        "items": [
+          { "label": "Introduction", "href": "/introduction" },
+          { "label": "Quick Start", "href": "/quickstart" }
+        ]
+      }
+    ]
+  },
+  "search": {
+    "enabled": true
+  }
+}
 ```
 
-### Update Templates
+### Core Config Keys (Portable)
 
-Templates are cached for 24 hours. Force update with:
+These work across all templates:
 
-```bash
-lito dev -i ./docs --refresh
+- `metadata` - Name, description, version
+- `branding` - Colors, logo, favicon
+- `navigation` - Sidebar, navbar
+- `search` - Search settings
+- `seo` - SEO configuration
+- `i18n` - Internationalization
+- `assets` - Asset paths
+
+### Extension Keys (Template-Specific)
+
+These may vary by template:
+
+- `footer` - Footer configuration
+- `theme` - Theme customization
+- `landing` - Landing page settings
+- `integrations` - Third-party integrations
+- `versioning` - Version settings
+
+## Analytics
+
+Add Google Analytics 4:
+
+```json
+{
+  "integrations": {
+    "analytics": {
+      "provider": "google-analytics",
+      "measurementId": "G-XXXXXXXXXX"
+    }
+  }
+}
 ```
 
 ## Documentation Structure
 
-Your docs folder should contain Markdown (`.md`) or MDX (`.mdx`) files:
-
 ```
 my-docs/
-├── index.md
+├── docs-config.json
+├── introduction.mdx
 ├── getting-started.md
 ├── api/
 │   ├── reference.md
 │   └── examples.md
-└── guides/
-    └── advanced.md
+├── _assets/          # Static assets
+├── _images/          # Images
+└── _landing/         # Custom landing (optional)
 ```
 
 ### Frontmatter
 
-Add frontmatter to your markdown files for better metadata:
-
 ```markdown
 ---
 title: Getting Started
-description: Learn how to get started quickly
+description: Learn how to get started
 ---
 
 # Getting Started
@@ -233,16 +439,15 @@ description: Learn how to get started quickly
 Your content here...
 ```
 
-## Architecture
-
-The CLI tool follows this pipeline:
+## Local Development
 
-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
+```bash
+git clone https://github.com/Lito-docs/cli.git
+cd cli
+pnpm install
+chmod +x bin/cli.js
+npm link
+```
 
 ## Contributing
 
@@ -251,7 +456,3 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## License
 
 MIT
-
----
-
-**Built with ❤️ using Astro and Node.js**