Turning ripples into waves

Building sites with Jekyll

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 ''
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, while the project root is located at 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 and not to the project site at

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!

In [2]:

This post was written as an IPython notebook. It is available for download or as a static html.

Creative Commons License
python4oceanographers by Filipe Fernandes is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Based on a work at