gpreview/README.md

Preview Ghost themes locally without a full Ghost installation

# Ghost Theme Preview

A lightweight, zero-config tool for previewing Ghost themes without running a full Ghost installation. Perfect for theme developers who want to test their Handlebars templates with mock data.

## Installation

```bash
# Install globally
npm install -g gpreview

# Or use npx without installing
npx gpreview /path/to/your/theme
```

## Quick Start

```bash
# Preview theme in current directory
gpreview

# Preview a specific theme
gpreview ./my-ghost-theme

# Use a custom port
gpreview ./my-ghost-theme -p 8080
```

## Features

- 🚀 **Zero Configuration** - Works out of the box with sensible defaults
- 🎨 **Full Theme Support** - Renders all standard Ghost templates (index, post, page, tag, author)
- 🔧 **Ghost Helpers** - Implements all essential Ghost Handlebars helpers
- 📦 **Built-in Mock Data** - Includes sample posts, authors, tags, and pages
- 🔄 **Hot Reload** - Changes to theme files are reflected immediately
- 📁 **Static Assets** - Automatically serves CSS, JS, and images from your theme
- 🎯 **Template Fallbacks** - Gracefully handles missing templates

## Usage

### CLI Options

```bash
gpreview [theme-path] [options]
```

- `theme-path` - Path to Ghost theme directory (default: current directory)
- `-p, --port <number>` - Port to run server on (default: 3000)
- `-d, --data <path>` - Path to custom mock data JSON file
- `-w, --watch` - Watch theme files for changes and auto-reload
- `-V, --version` - Output the version number
- `-h, --help` - Display help for command

### Examples

```bash
# Preview current directory as theme
gpreview

# Preview a specific theme
gpreview /path/to/casper

# Use a different port
gpreview ./my-theme -p 8080

# Watch for file changes
gpreview ./my-theme -w
```

## API Integration

You can also use this package programmatically:

```javascript
const { PreviewServer } = require('gpreview');

const server = new PreviewServer({
  themePath: './my-theme',
  port: 3000,
});

server.start().then(() => {
  console.log('Theme preview running on http://localhost:3000');
});
```

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Test with example themes
npm run preview dawn

# Run tests
npm test
```