22nd of March 2015
Jekyll is a very simple static web generator, which makes easier just to focus in the important thing, our web content rather than coding. It is specially design for blogging and it allows to use GitHub as a hosting platform, the result is a very simple tool which takes advantage of GitHub’s version control and allows people to create blogs in a very simple way using static HTML, it removes the complexity of other tools such as WordPress or Mephisto which needs to manage DDBB and other issues, an we only need to care about creating our content creating simple text file in Textile (“Markdown”).
To know more about Jekyll you can check this interesting post from its creator, Tom Preston Blogging Like a Hacker.
You can visit Jekyll’s official web and follow the installation tutorial, and probably you will get a wrong impression, it is not as easy at seems, truth to be told if we want to install Jekyll locally and deploy a web, things get complicated, so that I am going to try to explain the whole process I made explaining the doubts I had got and the problem I had.
GitHub allows to host public webs, it is free and the use github.io as a domain, in case you account to be a free account the complete domain name may be something like this user.github.io
We can create two kinds of webs: user and project, both are quite similar and both are deployed almost in the same way, user webs are hosted in a exclusive repository only for the web, and use the master branch to generate web connect, in the other hand, project webs are thought to share the repository with another project, in that case the content will be generated from the gh-pages branch.
We are going to use github-pages a tool provided by GitHub, it is a Ruby gem, in other words a Ruby package, ant will make thing easier to manage Jekyll and its dependencies avoiding version problems when deploying the web.
So far, so good, now we are going to follow step by step the tutorial provided by GitHub to use github-pages: GitHub Pages:
I am using Ubuntu 12.04 which already comes with Ruby 1.8, we can easily check this with the following command line:
$ ruby --version
Jekyll needs version 1.9.3 or higher so it needs to be updated, to avoid configuration problems a version clash, it is recommend to use RVM to manage and update our Ruby environment, probably our first thought will be to use the traditional package manager that comes with Linux ’$ apt-get’, but this constraints us to check decencies, version and gems conflicts, RVM safe us of all these worries and we can change Ruby version in a fast and easy way, it allows us to work in multiple Ruby environments independent and self-contained from each other.
First we need to install curl, you can find more information about curl here:
$ Apt-get install curl
To download RVM:
$ url -sSL https://get.rvm.io | bash -s stable
In case you have any problems with the signature, follow the steps in its web in its web
And now using RVM we can install and configure the Ruby version we need:
$ RVM install ruby-2.0
$ RVM use ruby-2.0
And last but not least, let’s check everything work out:
$ ruby --version
ruby 2.0.xxxxx
So far, so good, we already have install the Ruby version we need, and also some useful tools like RVM, a command-line tool which allows you to easily install, manage, and work with multiple ruby environments from interpreters to sets of gems, which personally I didn’t know before and I found very useful.
Bundler is a package manager for Ruby, provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed. We just need to create and edit a file in our project root path called Gemfile where we specify the source to download the gems and the gems we want to download, from here Bundle takes care of the whole process to detect and install the specified gems.
To install Bundler:
$ gem install bundler
We are going to use GitHub Pages to host the web, so that the first step is to a have a GitHub repository and clone it in our machine, we have already talk about the different kind of web we can generate using GitHub pages, user or project, in this case we are generating a user web (remember to work in the master branch), so we name the repository as follows: username.github.io, once it is created we clone it.
$ git clone https://github.com/username/username.github.io
In order to avoid dependency management, even in the GitHub Pages server as well as in our local environment (Markdown and other Jekyll dependencies), we follow the recommendation given by the Jekyll’s official web page and we use the gem given by GitHub called github-pages which will handle all dependencies for us, to install it we use Bundler, we only need to create a text file called Gemfile in the root of repository and we indicate which gems we want to download and the source, in our case:
source 'https://rubygems.org'
gem 'github-pages'
Ok, we have installed all the requirements in our local environment, so now lets try everything. Running Jekyll is very easy, we are going to use Bundler through the console using the exec command which uses the gems already specified in the Gemfile.
$ bundle exec jekyll serve
If everything worked out we should be able to check our page http://localhost:4000
So far I’ve only been using Jekyll for a matter of days to create this blog and write this post, I found it as a very powerful tool that avoid the user to take care of things such us DDBB or PHP, which is very useful. Maybe the most annoying thing is the official documentation, which I thing is scattered and disorganized, but just after a couple of working afternoons the feelings get better and better once the installation process have finished.
Here we conclude with the Jekyll installation process, in the following post I planned to cover how to configure it, customization and content generation.
Thanks for reading and I hope you find it useful.