Fixing Common Issues When Setting Up Jekyll & GitHub Pages on macOS

1️⃣ Understanding the Problem

If you’ve ever tried setting up a Jekyll-powered blog with GitHub Pages on macOS and ran into Ruby, Bundler, or dependency issues, you’re not alone! This guide walks you through troubleshooting and getting your blog up and running. 🚀

Common errors include:

• Wrong Ruby version (e.g., using system Ruby instead of a newer version)
• Bundler version mismatch (e.g., lockfile generated with an older Bundler)
• Permission issues when installing gems
• Conflicting dependencies when running bundle install

2️⃣ Fixing the Ruby Version

Check your installed Ruby versions:

rbenv versions

If you’re not using the latest version, set it manually:

rbenv install 3.1.4  # Install if missing
rbenv global 3.1.4   # Set it as default

Confirm with:

ruby -v  # Should return 3.1.4

3️⃣ Reinstalling Bundler & Cleaning Up Old Versions

Remove outdated Bundler versions and cached dependencies:

gem uninstall bundler
gem install bundler

Force Bundler to reconfigure:

rm -rf Gemfile.lock ~/.bundle ~/.gem
gem cleanup

4️⃣ Installing Jekyll & GitHub Pages

Navigate to your blog directory:

cd ~/the-long-beard-blog

Then reinstall dependencies:

bundle install

If dependency conflicts arise:

bundle update

For specific versions:

gem install jekyll -v 4.3.2
gem install github-pages -v 227

5️⃣ Running Your Blog Locally

Start the Jekyll server:

bundle exec jekyll serve

If it works, congrats! 🎉 If not, check the error messages and retry updating dependencies.

Final Thoughts

Keep your Ruby environment clean, update dependencies when needed, and happy blogging! 🚀