ImgFlow

A Jekyll plugin for automatic image optimization with multiple providers and formats.

🚀 Quick Start

# Add to your Gemfile
gem 'jekyll-imgflow'

# Install
bundle install

# Configure (_config.yml)
imgflow:
  originals: "assets/images/originals"
  output: "assets/images/optimized"
  sizes: {sm: 400, md: 800, lg: 1200}
  formats: [webp, avif, jpg]

# Use in templates
{% imgflow photo.jpg resize width:800 %}

✨ Key Features

  • Multiple Providers: Sharp, ImageMagick, LibVips, Imgproxy, Weserv, Flyimg
  • Modern Formats: WebP, AVIF, JPG, PNG with automatic fallbacks
  • Picture Tag Support: Full Jekyll Picture Tag compatibility
  • Build-Time Processing: Pre-generate images for optimal performance
  • Docker Services: Ready-to-use image processing containers
  • Parallel Testing: Fast test execution with CPU optimization

📚 Documentation

Getting Started

Configuration

Development

Performance

🏗️ Architecture Overview

ImgFlow has two processing flows: Build-Time (pre-generation) and Runtime (on-demand).

See: ARCHITECTURE.md for detailed component architecture and data flow

Quick Overview

  • Build-Time Flow - Pre-generate images during Jekyll build
  • Runtime Flow - Process images on-demand during template rendering
  • Providers - Image processing backends (CLI tools, HTTP APIs)
  • Tags - Jekyll template tags for image optimization

🎯 Provider Support

HTTP API Services (Recommended)

  • Imgproxy - Fast, reliable (Port 33001)
  • Weserv - Battle-tested (Port 33007)
  • Flyimg - On-the-fly processing (Port 33008)

CLI Tools (Local)

See: providers.md for detailed provider comparison and setup

🚀 Quick Commands

# Development
bundle exec jekyll serve              # Start development server
bundle exec jekyll build              # Build site

# Testing
rake quick                           # Quick checks (style + tests)
rake test                            # All tests
rake parallel:test                   # Parallel testing (faster)

# Docker Services
docker-compose -f docker-compose.test.yml up -d  # Start services
rake check_services                  # Verify services

See: testing.md for comprehensive testing guide, scripts.md for development utilities, and rake.md for all available Rake tasks

📦 Installation

Quick Setup

# Add to Gemfile
gem 'jekyll-imgflow'

# Install
bundle install

# Configure (_config.yml)
imgflow:
  originals: "assets/images/originals"
  output: "assets/images/optimized"
  sizes: {sm: 400, md: 800, lg: 1200}
  formats: [webp, avif, jpg]

# Use in templates
{% imgflow photo.jpg resize width:800 %}

See: installation.md for detailed installation instructions and configuration options

🐳 Docker Setup (Recommended)

# Start all services
docker-compose -f docker-compose.test.yml --env-file .env.test up -d

# Check services
rake check_services

# Stop services
docker-compose -f docker-compose.test.yml down

See: docker.md for detailed Docker configuration and services

🔄 Picture Tag Migration

ImgFlow provides full compatibility with Jekyll Picture Tag:

# Preview migration
bin/imgflow_migrate_presets --preview

# Migrate presets
bin/imgflow_migrate_presets

See: Picture Tag Migration Guide

📊 Performance

Latest benchmarks show Sharp as the fastest provider:

Provider Time (s) Speed
Sharp 13.97 🏆 Fastest
LibVips 21.89 Very Fast
Weserv 30.19 Fast
ImageMagick 30.62 Fast
Imgproxy 31.27 Fast

See: Provider Comparison for detailed benchmarks

🛠️ Development

Quick Setup

# Clone and setup
git clone <repository>
cd jekyll-imgflow
bundle install

# Download test images
rake download_test_images

# Run tests
rake quick

Key Files

  • lib/jekyll-imgflow.rb - Main module
  • lib/jekyll-imgflow/imgflow_tag.rb - Main tag implementation
  • lib/jekyll-imgflow/html_generator.rb - HTML generation
  • lib/jekyll-imgflow/picture_tag_adaptor.rb - Picture Tag compatibility

See: development.md for complete development setup, scripts, and workflows

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run rake quality to check all quality metrics
  6. Submit a pull request

See: development.md for detailed guidelines and scripts.md for development utilities

📄 License

This project is licensed under the AGPL-3.0-or-later License - see the LICENSE file for details.

🔗 Links

ImgFlow - Fast, flexible image optimization for Jekyll sites 🚀