Skip to content

INSTALLATION.md

Latest commit

 

History

History
163 lines (122 loc) · 4.48 KB

INSTALLATION.md

File metadata and controls

163 lines (122 loc) · 4.48 KB
Raw

🚀 StepTwo Gallery Scraper - Installation Guide

Quick Installation (Chrome Extension)

Method 1: Developer Mode (Recommended)

  1. Download the Extension

    git clone https://github.com/johnsonskyrme-sys/steptwo.git
cd steptwo

  2. Open Chrome Extensions Page

    • Go to chrome://extensions/ in Chrome
    • Enable "Developer mode" (toggle in top-right corner)

  3. Load the Extension

    • Click "Load unpacked"
    • Select the steptwo folder (containing manifest.json)
    • Extension should appear in your extensions list

  4. Pin the Extension

    • Click the puzzle piece icon (🧩) in Chrome toolbar
    • Find "StepTwo Gallery Scraper" and click the pin icon (📌)

Method 2: Package Installation

  1. Create Package

    npm run package

  2. Install Package

    • Go to chrome://extensions/
    • Drag and drop the generated .zip file from dist/ folder

🧪 Testing the Extension

Using the Test Server

  1. Start Development Server

    npm run dev

  2. Open Test Gallery

    • Navigate to http://localhost:3000/test-gallery.html
    • This page has sample images perfect for testing the extension

  3. Test Extension Features

    • Click the StepTwo extension icon
    • Try the "Start Quick Scan" feature
    • Test the manual picker mode
    • Experiment with different settings

Real-World Testing

  1. Visit Gallery Websites

    • Pinterest, Unsplash, Getty Images, Shutterstock
    • Any website with multiple images

  2. Use Extension Features

    • Popup interface for quick scanning
    • Windowed dashboard for advanced features
    • Options page for customization

🛠️ Development Setup

Prerequisites

  • Node.js (any recent version)
  • Chrome browser
  • Git

Development Workflow

  1. Clone and Setup

    git clone https://github.com/johnsonskyrme-sys/steptwo.git
cd steptwo
npm install  # No dependencies yet, but prepares package

  2. Validate Extension

    npm run validate
# Should show: ✅ Extension validation passed!

  3. Start Development Server

    npm run dev
# Access test galleries at http://localhost:3000

  4. Load Extension in Chrome

    • Follow installation steps above
    • Reload extension after making changes

🔧 Configuration

Basic Settings (Popup)

  • Auto-detect galleries: Automatically find image collections
  • Download images: Automatically download found images
  • Smart filtering: Remove duplicates and low-quality images
  • Pagination handling: Navigate through multiple pages

Advanced Settings (Options Page)

  • Performance tuning: Adjust delays and concurrent downloads
  • Custom selectors: Define specific CSS selectors for sites
  • Export formats: Choose JSON, CSV, Excel, or ZIP output
  • Filename patterns: Customize download naming

🎯 Key Features

🚀 Smart Detection

  • Automatically identifies image galleries
  • Works with modern JavaScript frameworks
  • Handles lazy-loading and dynamic content

🎨 Manual Selection

  • Point-and-click element picker
  • Visual overlay for precise selection
  • Generates optimized CSS selectors

📦 Export Options

  • JSON, CSV, Excel, HTML reports
  • ZIP packages with images and metadata
  • Customizable data fields and formats

🔧 Developer Tools

  • Built-in validation and testing
  • Development server with sample galleries
  • Extensible architecture for custom sites

📞 Support & Troubleshooting

Common Issues

Extension Won't Load

  • Ensure all files are present: npm run validate
  • Check Chrome console for errors
  • Verify manifest.json syntax

No Images Found

  • Try manual picker mode
  • Check if site uses dynamic loading
  • Review selector patterns in options

Performance Issues

  • Reduce concurrent downloads in settings
  • Enable memory optimization
  • Clear browser cache

Getting Help

🎉 Ready to Scrape!

Once installed, the StepTwo Gallery Scraper provides a powerful, user-friendly interface for extracting images from any website. The extension respects robots.txt, handles authentication through your browser session, and provides professional-grade export options.

Start with the test gallery at http://localhost:3000 to familiarize yourself with all features!