SETUP.md

🌱 Local Setup for GitHub Pages + Jekyll

This guide explains how to install and run Jekyll and GitHub Pages in a clean, isolated environment inside your project folder. This avoids global gem conflicts and ensures your site builds exactly the same way GitHub Pages does.

✅ 1. Clone or Open Your Jekyll Project

cd nicholas-misawo.github.io

You should confirm your project contains:

Gemfile
_config.yml
_posts/
index.md

If the project is missing a Gemfile, create one:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

✅ 2. Why You Should Avoid Installing Gems Globally

Running bundle install with no options installs gems into your global Ruby folder:

~/.gems/

This affects other Ruby projects and may cause version conflicts. GitHub Pages requires specific versions of Jekyll and related gems, so it’s best to isolate them.

🚀 3. Install Gems in a Project‑Local Environment

Inside your project folder, run:

bundle install --path vendor/bundle

This creates:

vendor/bundle/

This directory acts like a Ruby “virtual environment,” storing all gems needed for this project only.

▶️ 4. Run Jekyll Using the Local Environment

Always start Jekyll through Bundler:

bundle exec jekyll serve

Your site will be available at:

http://127.0.0.1:4000/

To stop the server:

CTRL + C

🧹 5. Cleaning Up (Optional)

If you previously installed gems system‑wide or want a clean state:

bundle clean --force

This removes unused bundled gems from the project.

🌟 6. Summary

Task	Command
Install isolated gems	`bundle install --path vendor/bundle`
Serve the site locally	`bundle exec jekyll serve`
Clean old bundles	`bundle clean --force`

❓ FAQ

Why does GitHub Pages require specific gem versions?

GitHub Pages builds sites on their own servers using fixed versions of Jekyll and plugins. Matching these versions locally ensures your site builds the same everywhere.

Where are gems stored when installed locally?

vendor/bundle/

You may safely delete this folder; Bundler will recreate it.

What about Ruby virtual environments?

Ruby doesn’t use Python‑style virtualenvs. Instead, Bundler creates isolated gem paths inside your project.

🎉 You’re Ready to Develop!

You now have a clean, conflict‑free Jekyll environment configured exactly the way GitHub Pages expects.

If you want, I can also generate a README.md, .gitignore, or add deployment instructions.