I am building a new website with Jekyll for work using the gh-pages framework. This post contains some notes to remind me how to do it.

Jekyll is a ruby tool (always wanted to try ruby out) to build static websites. GitHub uses Jekyll automatic under the hood. That means you do not need to push html to GitHub like I do with pelican for this blog. You just push the Jekyll structure and the site will be built automagically for you. For more information check GitHub Help page.

Now let's get our hand dirty! If you have ruby and bundler installed go ahead and install the github-pages gem. Create a text file called Gemfile with this:

source 'https://rubygems.org'
gem 'github-pages'

then just install github-pages bundle with (you might also need to install nodejs):

bundle install

To keep the bundle up-to-date use:

bundle update

Now we can create a blank page,

jekyll new website

and serve it locally at localhost:4000 to check the results.

cd website
 jekyll serve --watch --baseurl=

Jekyll will create a _site folder with the generated HTML. Make some modifications and you will see them appear in the browser (thanks to the watch option). If you need to build it manually just type jekyll build.

An important thing to remember is that a GitHub project site is different from a GitHub user/organization site. The user/organization has its root at http://user_or_organization.github.io, while the project root is located at http://user_or_organization.github.io/project. Why is this important? It will save you a world of pain to know that, when building a project site, you have to use the variable {{ site.baseurl }} for referencing files or pages in your website (like href and src) instead of just a /. The slash will always refer to the root at http://user_or_organization.github.io and not to the project site at http://user_or_organization.github.io/project.

For more information read Jekyll's documentation. Finally, here is the source code for the page I am building and the resulting website.

Now go have fun building websites for your projects!