Qasar Younis

Local Jekyll Testing Instructions

Local Jekyll Testing Instructions

Overview

Your site is a Jekyll-based GitHub Pages site. To test changes locally, you need to run Jekyll’s built-in development server on your machine.

Prerequisites Check

First, verify you have Ruby and Bundler installed:

ruby --version
bundle --version

If either command fails, you’ll need to install them first (see Installation section below).

Step-by-Step Instructions

1. Navigate to your project directory

cd /Users/qasaryounis/Desktop/qycowebsite/qasar.github.io

2. Install dependencies

Install all required gems (Jekyll and plugins) specified in your Gemfile:

bundle install

This will install:

3. Start the local Jekyll server

Important: Use the local config file so images load from your local assets folder:

bundle exec jekyll serve --config _config.yml,_config_local.yml

Or the shorter version:

bundle exec jekyll s --config _config.yml,_config_local.yml

Note: The _config_local.yml file sets the URL to empty for local development, so images will use relative paths (/assets/...) instead of the production URL (https://qy.co/assets/...). This file is in .gitignore so it won’t affect your production site.

4. View your site

Once the server starts, you’ll see output like:

Server address: http://127.0.0.1:4000/

Open your browser and navigate to: http://localhost:4000 or http://127.0.0.1:4000

5. Make changes and test

6. Stop the server

Press Ctrl + C in the terminal to stop the Jekyll server when you’re done testing.

Optional: Live Reload

To enable automatic browser refresh on changes, add the --livereload flag:

bundle exec jekyll serve --livereload

If Ruby/Bundler Not Installed

macOS Installation (using Homebrew):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Ruby
brew install ruby

# Install Bundler
gem install bundler

Alternative: Use rbenv or rvm

If you prefer version managers, you can use rbenv or rvm to manage Ruby versions.

Troubleshooting

Issue: “Could not locate Gemfile”

Issue: “Permission denied” errors

Issue: Port 4000 already in use

Issue: Changes not showing

Issue: “mkmf.rb can’t find header files for ruby” or “Failed to build gem native extension”

Issue: Ruby version too old (requires Ruby >= 3.0)

Notes