Installation Guide

This guide will help you set up the Jekyll development environment for your site.

Since macOS system Ruby requires sudo access, it’s recommended to use Homebrew to install a user-level Ruby.

Step 1: Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Ruby

brew install ruby

Step 3: Add Ruby to PATH

Add to your ~/.zshrc or ~/.bash_profile:

export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
export PATH="$(brew --prefix ruby)/bin:$PATH"

Then reload:

source ~/.zshrc  # or source ~/.bash_profile

Step 4: Install Bundler

gem install bundler

Step 5: Install Dependencies

cd ~/Developer/stu-jc.github.io
bundle config set --local path 'vendor/bundle'
bundle install

Step 6: Run Jekyll

bundle exec jekyll serve

Visit http://localhost:4000 to see your site!

Option 2: Using rbenv (Alternative)

Step 1: Install rbenv

brew install rbenv ruby-build

Step 2: Initialize rbenv

Add to your ~/.zshrc:

eval "$(rbenv init - zsh)"

Then reload:

source ~/.zshrc

Step 3: Install Ruby

rbenv install 3.2.2
rbenv global 3.2.2

Step 4: Install Bundler and Dependencies

gem install bundler
cd ~/Developer/stu-jc.github.io
bundle install

Step 5: Run Jekyll

bundle exec jekyll serve

Option 3: Using System Ruby with Local Install Path

If you prefer to stick with system Ruby:

Configure Bundler to Install Locally

cd ~/Developer/stu-jc.github.io
bundle config set --local path 'vendor/bundle'
bundle install

This installs gems to vendor/bundle in your project directory, avoiding permission issues.

Verifying Installation

After installation, verify everything works:

# Check Ruby version
ruby --version

# Check Bundler version
bundle --version

# Build the site
bundle exec jekyll build

# Serve the site locally
bundle exec jekyll serve

You should see output like:

Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

Common Issues

“Permission denied” errors

Solution: Use Option 1 or 3 above to avoid system Ruby.

“Command not found: bundle”

Solution: Install bundler:

gem install bundler

Port 4000 already in use

Solution: Use a different port:

bundle exec jekyll serve --port 4001

Bundler version issues

Solution: Update bundler:

gem install bundler
bundle update --bundler

Quick Reference

Once installed, these are the most common commands:

# Install/update dependencies
bundle install

# Run development server
bundle exec jekyll serve

# Run with live reload
bundle exec jekyll serve --livereload

# Build for production
bundle exec jekyll build

# Clean build files
bundle exec jekyll clean

Next Steps

After successful installation:

  1. ✅ Run bundle exec jekyll serve
  2. ✅ Visit http://localhost:4000
  3. ✅ Read JEKYLL_GUIDE.md for usage instructions
  4. ✅ Write your first blog post!
  5. ✅ Commit and push to deploy

Happy coding! 🚀