Jekyll Local Development Setup - Status

Date: October 31, 2025
Branch: dev
Goal: Set up local Jekyll development environment to test website changes

What is Bundler?

Bundler is a Ruby tool (like npm for Node.js or pip for Python) that:

Think of it as a package manager that reads your Gemfile and installs everything listed there.

Progress So Far

✅ Completed

  1. Created dev branch for safe testing
  2. Installed Ruby 3.4.7 via Homebrew (isolated from system Ruby)
  3. Installed Bundler 2.7.2 via Homebrew Ruby
  4. Updated Gemfile.lock to use Bundler 2.7.2 (was 2.1.4)

⚠️ Current Issue

Problem: The eventmachine gem (version 1.2.7) is failing to compile native extensions.

Error:

fatal error: 'iostream' file not found
make failed, exit code 2

Root Cause:

System Info:

Options to Fix (For Future Agent)

The Command Line Tools installation has incomplete C++ headers. Fix this first:

sudo rm -rf /Library/Developer/CommandLineTools/usr/include/c++
sudo ln -s /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++ /Library/Developer/CommandLineTools/usr/include/c++

Then retry bundle install with either Ruby version.

Option 1: Use Conda Environment (User’s Preference)

Create an isolated conda environment with an older Ruby version that’s compatible with github-pages:

conda create -n jekyll-env ruby=2.7
conda activate jekyll-env
cd /Users/tserre/Projects/tserre.github.io
gem install bundler
bundle install
bundle exec jekyll serve

Pros:

Cons:

Option 2: Update to Modern Jekyll

Remove github-pages gem and use a newer Jekyll version directly:

  1. Update Gemfile: 
    source 'https://rubygems.org'
gem "jekyll", "~> 4.3"
gem "jekyll-seo-tag"
gem "jekyll-theme-minimal"
  2. Run bundle update (will resolve newer compatible gems)

Pros:

Cons:

Option 3: Use rbenv with Ruby 2.7 (Alternative Isolation)

brew install rbenv ruby-build
rbenv install 2.7.8
cd /Users/tserre/Projects/tserre.github.io
rbenv local 2.7.8
gem install bundler
bundle install
bundle exec jekyll serve

Files Modified

✅ SETUP COMPLETE!

Date: October 31, 2025, Evening

Final Solution:

  1. ✅ Fixed C++ headers by creating proper symlink (user action)
  2. ✅ Installed Ruby 3.3.0 via rbenv (compatible with eventmachine)
  3. ✅ Installed Jekyll 4.4.1 with all dependencies
  4. ✅ Server running successfully at http://localhost:4000

Lessons Learned:

How to Use

Start the server:

cd /Users/tserre/Projects/tserre.github.io
eval "$(rbenv init - zsh)"  # Make sure rbenv is active
bundle exec jekyll serve
# Opens at http://localhost:4000

Make changes:

Stop the server:

Testing Commands (Once Fixed)

# Navigate to project
cd /Users/tserre/Projects/tserre.github.io

# Make sure you're on dev branch
git checkout dev

# Start local server
bundle exec jekyll serve

# Visit http://localhost:4000 in browser
# Make changes to files and see them update automatically

Notes for Future Agent

Useful Resources