simple-photo-gallery 0.0.8 → 2.0.1

package/README.md

@@ -1,349 +1,80 @@
-# Simple Photo Gallery CLI
+# Simple Photo Gallery
 
-A command-line tool for creating beautiful photo galleries from your image and video collections. This CLI helps you scan directories, generate thumbnails, and set up Astro-based gallery websites.
+Create beautiful photo galleries from collections in just 30 seconds. No configuration required to get started—simply run two commands in your photos folder and create a static gallery website you can self-host.
 
-## Features
-
-- 📸 **Media Scanning**: Automatically scan directories for images and videos
-- 🖼️ **Thumbnail Generation**: Create optimized thumbnails for fast loading
-- 🎥 **Video Support**: Handle video files with ffmpeg integration
-- 📱 **Responsive Design**: Generate galleries that work on all devices
-- ⚡ **Fast Performance**: Optimized thumbnails and lazy loading
-- 🔧 **Astro Integration**: Seamless setup with Astro static site generator
-
-## Installation
-
-### Prerequisites
-
-- Node.js 18+
-- npm or yarn
-- ffmpeg (for video processing)
-
-### Install ffmpeg
-
-**macOS:**
-
-```bash
-brew install ffmpeg
-```
-
-**Ubuntu/Debian:**
-
-```bash
-sudo apt update
-sudo apt install ffmpeg
-```
-
-**Windows:**
-Download from [ffmpeg.org](https://ffmpeg.org/download.html)
-
-### Install the CLI
-
-```bash
-# Clone the repository
-git clone <repository-url>
-cd simple-photo-gallery-public/cli
-
-# Install dependencies
-npm install
-
-# Build the CLI
-npm run build
-
-# Link globally (optional)
-npm link
-```
-
-## Commands
-
-### `gallery init`
-
-Scan a directory for images and videos to create a `gallery.json` file.
-
-```bash
-gallery init [options]
-```
-
-**Options:**
-
-- `-p, --path <path>` - Path to scan for media files (default: current directory)
-- `-o, --output <path>` - Output directory for gallery.json
-- `-r, --recursive` - Scan subdirectories recursively
+This is a free, open-source tool that you can use to generate galleries and self-host them. If you don't want to use the command line or bother with self-hostting, please check out [simple.photo](https://simple.photo) for a hosted solution.
 
-**Examples:**
+## Example Gallries
 
-```bash
-# Scan current directory
-gallery init
-
-# Scan specific directory
-gallery init --path /path/to/photos
-
-# Scan recursively
-gallery init --path /path/to/photos --recursive
-
-# Specify output directory
-gallery init --path /path/to/photos --output /path/to/output
-```
-
-### `gallery thumbnails`
-
-Generate thumbnails for all media files in the gallery.
-
-```bash
-gallery thumbnails [options]
-```
-
-**Options:**
-
-- `-p, --path <path>` - Path containing .simple-photo-gallery folder (default: current directory)
-- `-s, --size <size>` - Thumbnail height in pixels (default: 200)
-
-**Examples:**
-
-```bash
-# Generate thumbnails with default size
-gallery thumbnails
-
-# Generate thumbnails with custom size
-gallery thumbnails --size 300
-
-# Specify gallery path
-gallery thumbnails --path /path/to/gallery
-```
-
-### `gallery build`
-
-Configure Astro template to work with external image directories and build galleries.
-
-```bash
-gallery build [options]
-```
-
-**Options:**
-
-- `-i, --images-path <path>` - Path to images directory (required)
-- `-r, --recursive` - Scan subdirectories recursively for gallery/gallery.json files
-
-**Examples:**
-
-```bash
-# Setup template for a single gallery directory
-gallery build --images-path ../my-photos
-
-# Setup template recursively for multiple gallery directories
-gallery build --images-path ../my-photos --recursive
-```
+<div align="center">
+  <a href="https://simple.photo/demo-australia">
+    <img src="docs/images/simple-photo-gallery-demo.jpg" alt="Simple Photo Gallery Demo" width="50%">
+  </a>
+</div>
 
-## Complete Workflow Examples
+### More examples
 
-### Basic Gallery Creation
+- [California Road Trip](https://simple.photo/demo-california)
+- [Visiting Australia](https://simple.photo/demo-australia)
+- [Discovering Japan](https://simple.photo/demo-japan)
 
-1. **Prepare your photos directory:**
-
-```bash
-mkdir my-photos
-# Copy your photos and videos to my-photos/
-```
-
-2. **Scan for media files:**
-
-```bash
-cd my-photos
-gallery init
-```
-
-3. **Generate thumbnails:**
-
-```bash
-gallery thumbnails --size 250
-```
-
-4. **Set up Astro template:**
-
-```bash
-cd ../template
-gallery build
-```
-
-5. **Build and serve:**
-
-```bash
-npm run dev
-```
-
-### Advanced Workflow with Multiple Sections
-
-1. **Organize photos in subdirectories:**
-
-```
-my-photos/
-├── vacation/
-│   ├── beach.jpg
-│   ├── mountains.jpg
-│   └── sunset.mp4
-├── family/
-│   ├── birthday.jpg
-│   └── christmas.jpg
-└── events/
-    ├── wedding.jpg
-    └── graduation.jpg
-```
-
-2. **Scan with recursive option:**
-
-```bash
-cd my-photos
-gallery init --recursive
-```
-
-3. **Edit gallery.json to create sections:**
-
-```json
-{
-  "title": "My Photo Collection",
-  "description": "A collection of my favorite moments",
-  "headerImage": "vacation/beach.jpg",
-  "metadata": { "ogUrl": "" },
-  "sections": [
-    {
-      "title": "Vacation Memories",
-      "description": "Amazing trips and adventures",
-      "images": [
-        // vacation images will be here
-      ]
-    },
-    {
-      "title": "Family Moments",
-      "description": "Precious family memories",
-      "images": [
-        // family images will be here
-      ]
-    },
-    {
-      "title": "Special Events",
-      "description": "Important life events",
-      "images": [
-        // events images will be here
-      ]
-    }
-  ]
-}
-```
+## Features
 
-4. **Generate thumbnails:**
+    📸 Automatically scan directories with photos and videos
+    📝 Show descriptions for photos and videos
+    📂 Divide the gallery into sections to tell a story
+    🖼️ Create optimized thumbnails for fast loading
+    🎥 Play videos directly in the gallery
+    📱 Generate galleries that work on all devices
+    ⚡ Optimized to be fast and lightweight
+    🔧 Generate a static HTML gallery that you can self-host
 
-```bash
-gallery thumbnails --size 300 --recursive
-```
+## Quick Start
 
-5. **Set up and build:**
+The fastest way to create a gallery is to use `npx` in your photos folder:
 
 ```bash
-cd ../template
-gallery build --recursive
-```
-
-## File Structure
-
-After running the CLI, your project will have this structure:
-
+npx simple-photo-gallery init
+npx simple-photo-gallery build
 ```
-my-photos/
-├── .simple-photo-gallery/
-│   ├── gallery.json          # Gallery metadata and file list
-│   └── thumbnails/           # Generated thumbnails
-│       ├── image1.jpg
-│       ├── image2.jpg
-│       └── video1.jpg
-├── photo1.jpg
-├── photo2.jpg
-└── video1.mp4
-
-template/
-├── astro.config.ts           # Modified Astro config
-├── gallery.json              # Copied gallery data
-└── ... (other Astro files)
-```
-
-## Supported Media Formats
-
-**Images:**
-
-- JPEG (.jpg, .jpeg)
-- PNG (.png)
-- WebP (.webp)
-- GIF (.gif)
-- TIFF (.tiff, .tif)
-
-**Videos:**
-
-- MP4 (.mp4)
-- MOV (.mov)
-- AVI (.avi)
-- WebM (.webm)
-- MKV (.mkv)
 
-_Note: Video processing requires ffmpeg to be installed and available in your PATH._
+This will:
 
-## Troubleshooting
+1. Install the [simple-photo-gallery](https://www.npmjs.com/package/simple-photo-gallery) package from NPM (if you don't already have it)
+2. Prompt you for your gallery title, description, and header image
+3. Scan your photos and create a `gallery.json` file
+4. Generate optimized thumbnails
+5. Build a static HTML gallery that you can open in your browser and self-host
 
-### Common Issues
+## Installation Requirements
 
-**"ffprobe not found" error:**
+- **Node.js 20+** - [Download here](https://nodejs.org/)
+- **FFmpeg** (for video support) - Install via:
+  - macOS: `brew install ffmpeg`
+  - Ubuntu/Debian: `sudo apt install ffmpeg`
+  - Windows: [Download from ffmpeg.org](https://ffmpeg.org/download.html)
 
-- Install ffmpeg: `brew install ffmpeg` (macOS) or `sudo apt install ffmpeg` (Ubuntu)
-- Ensure ffmpeg is in your PATH
+## Supported Formats
 
-**"Gallery not found" error:**
+**Images:** JPEG, PNG, WebP, GIF, TIFF  
+**Videos:** MP4, MOV, AVI, WebM, MKV
 
-- Run `gallery init` first to create the gallery.json file
-- Check that the path to .simple-photo-gallery folder is correct
+## Detailed Documentation
 
-**Thumbnail generation fails:**
+For advanced usage, customization, and deployment options, see the comprehensive [documentation](./docs/README.md):
 
-- Check file permissions
-- Ensure sufficient disk space
-- Verify media files are not corrupted
+- **[Commands Reference](./docs/commands/README.md)** - Detailed guide for all CLI commands
+  - [`init`](./docs/commands/init.md) - Initialize new galleries
+  - [`build`](./docs/commands/build.md) - Generate static HTML galleries
+  - [`thumbnails`](./docs/commands/thumbnails.md) - Generate optimized thumbnails
+  - [`clean`](./docs/commands/clean.md) - Remove gallery files
+- **[Gallery Configuration](./docs/configuration.md)** - Manual editing of `gallery.json` and advanced features like sections
+- **[Deployment Guide](./docs/deployment.md)** - Guidelines for hosting your gallery
 
-### Getting Help
+## Python Version
 
-- Check that all required dependencies are installed
-- Verify file paths are correct and accessible
-- Ensure ffmpeg is properly installed for video processing
-- Review the generated gallery.json file for any issues
-
-## Development
-
-### Building from Source
-
-```bash
-# Install dependencies
-npm install
-
-# Build the CLI
-npm run build
-
-# Run in development mode
-npm run gallery
-```
-
-### Code Quality
-
-```bash
-# Check TypeScript
-npm run check
-
-# Lint code
-npm run lint
-
-# Fix linting issues
-npm run lint:fix
-
-# Format code
-npm run format
-```
+The old Python version of Simple Photo Gallery V1 is still available [here](https://github.com/haltakov/simple-photo-gallery), but is now deprecated.
 
 ## License
 
-MIT License - see LICENSE file for details.
+Simple Photo Gallery is licensed under the MIT License - see [LICENSE](./LICENSE) file for details.