Jekyll Migration Script
Jekyll Site Management Script
This document explains a shell script designed to simplify the migration, building, and deployment of a Jekyll website. It automates the process of cleaning up outdated dependencies and deploying your site to a remote server. It worked for me. It may not work for you.
Make sure you backup your site/data/posts before using. Make sure you test extensively. This script can delete all your data. Do NOT use without testing extensively. You should test the script manually by executing each step manually on test data before automating.
Script Purpose
This script addresses common issues that arise when moving a Jekyll project to a new machine or when gem dependencies conflict.
Its primary functions are:
Dependency Cleanup: It removes the Gemfile.lock and .bundle directories, forcing Bundler to resolve and install the latest compatible versions of all gems. This fixes “LoadError” issues and other dependency conflicts.
Version Management: It modifies your Gemfile to remove strict version numbers, allowing you to automatically use the latest, most up-to-date versions of Jekyll and its dependencies.
Site Build: It builds your site for production, ensuring all assets are correctly generated.
Usage:
To use the script, save the code below as a file (e.g., fix_jekyll.sh), make it executable, and then run it from your terminal.
chmod +x fix_jekyll.sh
To run the script, pass the path to your Jekyll project directory as the first argument:
./fix_jekyll.sh ~/path/to/your-jekyll-site
The Script - MAKE SURE YOU TEST THE SCRIPT WITH TEST DATA BEFORE USING. You CAN LOSE ALL YOU DATA WITH THIS SCRIPT. USE AT YOUR OWN RISK.
#!/bin/bash
# --- Script Description ---
# This script is designed to streamline the management of a Jekyll website.
# It automates several common maintenance tasks that can be tedious or
# prone to error when performed manually, such as:
# 1. Navigating to the correct project directory.
# 2. Cleaning up previous build artifacts and dependency caches.
# 3. Ensuring that the site's dependencies are up-to-date.
# 4. Building and serving the site for local development.
# The script is robustly built to handle potential errors and provide clear
# feedback to the user at each step.
# --- Error Handling ---
# Exit the script immediately if any command fails. This is crucial for
# preventing the script from proceeding with subsequent commands if a
# prerequisite step (like changing directories) fails.
set -e
# --- Input Validation ---
# Ensure a single command-line argument (the project directory) is provided.
# If not, print a usage message and exit with an error code.
if [ "$#" -ne 1 ]; then
echo "Usage: $0 <path_to_jekyll_project>"
exit 1
fi
# --- Main Script Logic ---
PROJECT_DIR="$1"
# Print a message indicating which project the script is working on.
echo "Working on project in directory: $PROJECT_DIR"
# Change the current working directory to the project directory.
# This ensures all subsequent commands (like `bundle` and `jekyll`) are
# executed in the correct context.
cd "$PROJECT_DIR"
# Step 1: Clean up old dependency files.
# Removing Gemfile.lock forces Bundler to resolve and install the latest
# compatible gem versions from Gemfile, which can fix dependency conflicts.
echo "Removing Gemfile.lock..."
rm -f Gemfile.lock
# Remove the .bundle and .jekyll-cache directories to ensure a clean build.
# This helps prevent issues with cached gems or corrupted build data.
if [ -d ".bundle" ]; then
echo "Removing .bundle directory..."
rm -rf .bundle
else
echo ".bundle directory not found, skipping."
fi
if [ -d ".jekyll-cache" ]; then
echo "Removing .jekyll-cache directory..."
rm -rf .jekyll-cache
else
echo ".jekyll-cache directory not found, skipping."
fi
# Step 2: Fix Gemfile for versioning and missing gems.
# The sed commands modify the Gemfile in place to:
# a) Remove strict version constraints on the `github-pages` gem.
# This allows Bundler to choose a compatible version that may be
# newer or older than the one originally specified, increasing flexibility.
# b) Add the 'logger', 'csv', 'base64', and 'bigdecimal' gems to the Gemfile.
# These are no longer part of the default gems in newer Ruby versions and
# are required by Jekyll. Adding them explicitly resolves common
# `LoadError` issues.
echo "Updating Gemfile for compatibility..."
sed -i '' 's/gem \"github-pages\".*$/gem \"github-pages\"/' Gemfile
# Add 'logger', 'csv', 'base64', and 'bigdecimal' gems to the Gemfile to prevent Ruby 3.4+ LoadErrors
if ! grep -q "gem 'logger'" Gemfile; then
echo "gem 'logger'" >> Gemfile
fi
if ! grep -q "gem 'csv'" Gemfile; then
echo "gem 'csv'" >> Gemfile
fi
if ! grep -q "gem 'base64'" Gemfile; then
echo "gem 'base64'" >> Gemfile
fi
if ! grep -q "gem 'bigdecimal'" Gemfile; then
echo "gem 'bigdecimal'" >> Gemfile
fi
# Step 3: Install dependencies.
# This command installs all gems specified in the Gemfile, ensuring the
# local environment is set up correctly for the Jekyll site.
echo "Installing new dependencies with Bundler..."
bundle install
# Step 4: Build and serve the site.
# This command builds the site (generating the `_site` directory) and
# starts a local server to preview the site.
echo "Building and serving the site..."
bundle exec jekyll serve
echo "Script finished successfully!"