GitHub Pages Local Jekyll Guide.md

Developing a Website using GitHub Pages Locally on Ubuntu

This is a simple step-by-step guide to setup your system to develop a website that will be deployed on GitHub Pages locally.

Install ruby and dependencies

First of all you need to install the proper packages using apt:

sudo apt install ruby-full build-essential zlib1g-dev -y

Then we need to add to your preferred shell run-commands file the path to ruby gems executable.

This can be whatever you want, but it should reside within your home folder, as we will perform per-user installations of ruby gems. Usually it is either ~/gems or ~/.gems. I prefer the latter, because my visible folders are much cleaner this way.

If you don't know what rc file you should edit, check first which shell you use. If you use bash, of course you know it is the ~/.bashrc file. Since I use zsh, I will use `/.zshrc file:

echo '' >> ~/.zshrc
echo '# Install Ruby Gems to ~/.gems' >> ~/.zshrc
echo 'export GEM_HOME="$HOME/.gems"' >> ~/.zshrc
echo 'export PATH="$HOME/.gems/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install the bundler

Now that you are ready you can install gems locally. First of all bundler gem will be needed to build the website using Jekyll. Also, jekyll gem of course is needed, but it will be automatically fetched by the bundler, so we can avoid to install it for now. Notice also that when I am writing the current version of Jekyll is the 4.0.0, while GitHub Pages use 3.8.5. This could lead to problems if Jekyll is installed manually, so we will leave Jekyll installation to an automatic task.

To install the bundler run:

gem install bundler

And that's it for now.

Cloning your website from GitHub

Once you have set up your GitHub repository to use GitHub Pages (installing a theme might be useful, because it provides also a theme for code highlight) you can clone the repo locally.

Setting up the Gemfile and dependencies

Once you are done you'll need to create a Gemfile file in the root of the project (I guess, I use the root to provide the website, if you use a custom branch or folder to provide the website for your project hosted on github it might be different), containing the following lines:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

This will import all the packages and dependencies needed to test your website just like it will perform once uploaded to GitHub.

To then finalize the process run

bundle update

this will generate a file Gemfile.lock which will be used by bundler to setup your system each time you clone the repository way faster. GitHub Pages ignore the content of the Gemfile.lock file, so don't worry too much about it.

Build and Run

To build your website you can then use

bundle exec jekyll build

And once done you can run a jekyll-based web server by using

bundle exec jekyll serve

From a few versions ago, running jekyll serve should automatically rebuild and update the served website on save of certain files, like one would expect by doing

bundle exec jekyll build --watch &
bundle exec jekyll serve

so probably simply running bundle exec jekyll serve should suffice.

And that's it! You are now ready to develop locally your website and then push it to GitHub Pages (hopefully!) without issues.