Sandbox Jekyll documentation
Rake Build System
Comprehensive guide to the Rake build system in the Sandbox theme
Understanding Rake
What is Rake?
Rake (Ruby Make) is a build automation tool written in Ruby. In the Sandbox theme, it handles:
- Development server management
- Production builds
- Asset optimization
- Image processing
- Task automation
Prerequisites
Required software and dependencies:
- Ruby (version 2.7.0 or higher)
- RubyGems
- Bundler gem
- ImageMagick or Vips (for image processing)
# Install Ruby dependencies
gem install bundler
# Install ImageMagick (MacOS)
brew install imagemagick
# Install ImageMagick (Ubuntu/Debian)
sudo apt-get install imagemagick
# Install project dependencies
bundle install
Windows Installation Guide
Installing ImageMagick on Windows:
- Download the appropriate installer:
- Visit the ImageMagick Windows Download Page
- Choose the appropriate version (recommended: Q16-HDRI-x64)
- Example filename:
ImageMagick-7.1.1-21-Q16-HDRI-x64-dll.exe
- During installation:
- Check “Add to system PATH”
- Check “Install development headers and libraries for C and C++”
- Check “Install legacy utilities (e.g. convert)”
- Verify installation:
- Open Command Prompt
- Run
magick -version
Common Windows Issues:
1. "Convert not found" error:
- Rename "convert.exe" to "imagemagick-convert.exe" in ImageMagick installation directory
- This prevents conflicts with Windows system convert.exe
2. PATH issues:
- Open System Properties
- Click "Environment Variables"
- Add ImageMagick directory to Path (typically C:\Program Files\ImageMagick-7.x.x-Q16)
3. Ruby gem installation fails:
- Install Visual Studio Build Tools
- Run: `ridk install` (select options 1, 2, and 3)
- Reinstall the gem
4. DLL load failed:
- Install Visual C++ Redistributable
- Download from Microsoft's website
- Install both x86 and x64 versions if unsure
System Requirements
Windows-specific requirements:
- Windows 10 or later (recommended)
- Visual C++ Redistributable 2015-2022
- Visual Studio Build Tools (for gem installation)
- At least 2GB free disk space
- Administrator privileges for installation
Core Functionality
Development Server
The serve task provides a development environment with:
- Live reload capability
- Automatic Sass compilation
- Vendor file processing
- Asset watching
desc "Serve the site"
task :serve => [:prepare] do
begin
$logger.info "Starting development server..."
sh "bundle exec jekyll serve --livereload --livereload-min-delay 5 --trace"
rescue => e
$logger.error "Serve error: #{e.message}"
raise
end
end
Production Build
The build task creates production-ready assets:
- Minified CSS and JavaScript
- Optimized images
- Compiled Jekyll site
- Environment-specific configurations
desc "Build the site"
task :build => [:prepare] do
begin
$logger.info "Building site for production..."
sh "JEKYLL_ENV=production bundle exec jekyll build"
rescue => e
$logger.error "Build error: #{e.message}"
raise
end
end
Image Processing
WebP Conversion
Automated image optimization features:
- Batch conversion to WebP format
- Original file preservation options
- Size optimization reporting
- Configurable quality settings
# Convert images to WebP
bundle exec rake convert_to_webp
# Optimize and remove originals
bundle exec rake optimize_images[true]
# Remove original files
bundle exec rake remove_originals
Best Practices
Development Workflow
Recommended development workflow:
- Start development server:
bundle exec rake serve - Make changes to source files
- Test in development environment
- Optimize images if needed
- Build for production:
bundle exec rake build
Performance Tips
Optimize build performance:
- Use incremental builds during development
- Process images in batches
- Maintain clean asset directories
- Regular cache clearing
Troubleshooting
Common Issues
Solutions for frequent problems:
- Missing Dependencies: Run
bundle install - Port Conflicts: Change port in configuration
- Build Failures: Check error logs and Jekyll environment
- Image Processing Errors: Verify ImageMagick installation
Debugging
Debug Rake tasks:
- Enable verbose mode:
rake -v task_name - Check Jekyll logs in
_site/build.log - Use
--traceflag for detailed stack traces - Monitor system resources during builds
Advanced Usage
Custom Tasks
Create custom Rake tasks in Rakefile:
desc "Custom task description"
task :custom_task do
puts "Executing custom task..."
# Add your custom logic here
end
# Task with dependencies
task :custom_task_with_deps => [:prepare, :build] do
# This task runs after prepare and build
end