28 December 2011 - Lisbon

Introduction

As you know there are lots of blogging engine out there (Wordpress, Blogger, etc). Several years ago I have used to blog on the Wordpress, then again on Posterous; however, I never really liked them. There are lots of bloated things, and if you want to change, for instance, a theme it is painful. You should learn their theming system etc. Blogging should be as easy as firing up your favorite text editor and writing on it. After doing some (re)search I came across several posts about “Blogging Like a Hacker”.

Therefore, I gave it a try. If you like simple blogging and clean themes, moreover, if you want full control over your blogging engine you are on the right place. In this post I will try to explain how to setup blogging engine using Jekyll and Github Pages.

Blogging Engine in a Half an Hour

A Lot of people use GitHub for code repository hosting, but you can also do webhosting with your GitHub account. It is source controlled and free, after pushing to a git repository you GitHub Page is deployed automatically. Your static website is generated by Jekyll from plain text post files and layout templates. After pushing new posts to GitHub, Jekyll is run on the files and the static site is generated and hosted for you. In order to setup all, I have followed the David Winter’s Post you can also look to that post as well. (I have setup all these in my Ubuntu 11.10 machine, installing to Mac and Windows should not be different.)

To get started, install rubygems (this is required in order to install Jekyll).

$ sudo apt-get install rubygems

Then install Jekyll

$ sudo gem install jekyll

Mostly posts are written in Markdown, Textile or plain html. I will be using Markdown, so we need to install rdiscount in order to use it.

$ sudo gem install rdiscount

Now let’s create a git repository to manage your blog. You can set up all configurations by yourself but, for the sake of simplicity, let’s clone the bare bones of the Jekyll base site.

> git clone https://github.com/danielmcgraw/Jekyll-Base.git yourgithubusername.github.com

Replace yourgithubusername with your GitHub username.

Now, we don’t want the git history for this skeleton setup, so remove the .git directory:

$ cd yourgithubusername.github.com/ $ rm -rf
.git

At this stage you should have working system, in order to test open another terminal, go to the same directory and run Jekyll locally,

$ jekyll --server

(This might give some errors about specification file, in that case find that file and remove the time from date written there). This will run the webserver on the port 4000, monitoring file changes and applying the changes automatically on the fly. Therefore, keep this terminal open and runnning.

You should now be able to see the generated site locally by visiting http://localhost:4000.

When jekyll builds the site, it puts the generated files into a _site directory. You don’t want this directory in Git repository, so in the .gitignore file add _site to the bottom so that it’ll be ignored.

$ echo "_site" >> .gitignore

At this stage you should have fully working local Jekyll server engine. Now login to GitHub and create a new repository with the same name as yourgithubusername.github.com. If this is your first repository in the GitHub, it will lead you to a process of how to configure your local machine, i.e, setting ssh key and global configurations. It won’t take a minute.

Then from your local machine.

$ cd yourgithubusername.github.com
$ git init
$ git add .
$ git commit -m "Initial commit. Jekyll base setup."

Then follow GitHub’s instructions on adding the remote reference, which is along the lines of (substitute username),

$ git remote add origin
git@github.com:username/username.github.com.git $ git push -u origin
master

This pushes your initial site to the GitHub. It can take up to 10 minutes for new sites to be generated when they are first pushed. They will email you when it’s done.

Moreover, after these steps whenever you make new changes or write a new blog post, you have only to do,

$ git commit -am "Wrote another awesome blog!"
$ git push origin

Now you are able to visit your static site from http://yourgithubusername.github.com

Further Steps

From now on you can modify your site using HTML/CSS (I do not speak this language.) with full control over the blogging engine. Create themes of your liking, modify color, text, etc. For inspiration visit the Sites created by GitHub Pages. I have cloned the Tom Preston-Werner’s site and, currently I am happy with it. Maybe I will learn some html/css while making the changes to the site.

References

  • Jekyll Wiki — Covers more features and configuration options for Jekyll.
  • GitHub Pages — An explanation on how to set up your personal GitHub page as well as how to set up pages for your projects.
  • YAML Front Matter — Metadata for files that will be processed by Jekyll.
  • Liquid Templating Language — The Ruby templating engine used by Jekyll.
  • Markdown — For simply editing posts.