Automatic Image Thumbnails for Jekyll

Scans your rendered HTML for local images with width or height attributes, then automatically generates and uses appropriately-sized thumbnails for them, if the src image is bigger than that.

Can also take global maximum dimensions (such as for fixed-width layouts) and thumbnail images that don't have explicit size attributes, too.

Requires ImageMagick to be installed.

Add to your Gemfile:

group :jekyll_plugins do
  gem "jekyll-auto-thumbnails"
end

Run:

bundle install

System Requirement: ImageMagick must be installed. The gem supports both:

• ImageMagick 6: Uses convert and identify commands directly
• ImageMagick 7: Uses magick convert and magick identify (automatically detected)

# _config.yml
auto_thumbnails:
  enabled: true  # default: true
  
  # Maximum dimensions for automatic thumbnailing
  # Images exceeding these get thumbnails even without explicit sizing
  max_width: 1200   # pixels (optional)
  max_height: 800   # pixels (optional)
  
  # JPEG quality for generated thumbnails (0-100)
  quality: 85  # default: 85

1. HTML Scanning: After all plugins run, scans <article> tags for images
2. Size Detection:
   • Images with width or height attributes → uses those dimensions
   • Unsized images exceeding max config → thumbnails to max dimensions
3. Generation: Creates thumbnails with MD5-based caching in .jekyll-cache/
4. URL Replacement: Updates <img src> to point to thumbnails
5. File Copying: Copies thumbnails to _site/ after build

<article>
  <img src="/photo.jpg" width="300" height="200">
  <!-- Generates: photo_thumb-abc123-300x200.jpg -->
</article>

# _config.yml
auto_thumbnails:
  max_width: 800

<article>
  <img src="/big-photo.jpg">
  <!-- If photo is 2000x1500, generates: big-photo_thumb-def456-800x600.jpg -->
</article>

Works automatically with any Markdown processor, because it checks the rendered HTML!

![Photo](photo.jpg)  <!-- Auto-detects size -->

• First build: Generates thumbnails, stores in .jekyll-cache/
• Subsequent builds: Reuses cached thumbnails (fast!)
• Source changed: MD5 mismatch detected, regenerates automatically
• Dimensions changed: Different filename, generates new thumbnail

# Ubuntu/Debian
sudo apt-get install imagemagick

# macOS
brew install imagemagick

# Verify installation
# ImageMagick 6:
which convert identify
# ImageMagick 7:
which magick

The gem automatically detects which version you have installed and uses the appropriate commands.

Check build output for warnings:

bundle exec jekyll build --verbose
# Look for "AutoThumbnails:" messages

rm -rf .jekyll-cache/jekyll-auto-thumbnails/