Building your first Jekyll site in 5 minutes

Back in December, I wrote a short post about building websites without server side includes. I used AJAX and magical hasbang url’s to get around the fact that the hosting space I was given on the university servers did not support any kind of scripting. I basically outsourced my scripting to the client side – it happens dynamically in the browser. Unfortunately, my solution lacks in accessibility. It’s still possible to navigate my site without JavaScript but the experience is diminished.

There is alternate way to do this. A proper way if you will – one that still allows you to keep your design templates separate from your data, but one which will produce great looking static html sites with no scripting required. One that moves the heavy lifting (includes, imports, processing, etc..) from run time, to compile time.

Let’s think about this for a second – the main reason we use server side (or client side like in my example) scripting for web design is so that we don’t have to copy and paste the same headers, footers, and css references into every single html file. We design a great looking template, with blank holes. Then at run time, we use some magic to import content into these holes to generate “nice” HTML files that are then served to the user. There is technically no reason why we couldn’t do all that importing and generating at the design stage though. We could easily pre-process our page just before deployment, and then upload only the resulting static HTML to the server. Granted, this is not going to work for pages that accept and process user input. But it is fine for a simple home page, or a blog. All you need is a good pre-processing tool.

That tool is Jekyll.

What the hell is Jekyll, you ask?

Jekyll is a nifty little Ruby gem, that will take your template pages, your content data and transform them into a set of static HTML files that can be deployed anywhere. In other words, it is a “website compiler”.

How does it work, you ask?

Do you really want to know the details? Do you care? Here is the source code. Go enlighten yourself. Everyone else, here is the functional explanation:

1. You make a folder
2. In that folder you put some files
3. You run Jekyll
4. A static HTML website pops out in _site directory

That’s about as complicated it gets. The main problem with Jekyll is step #2. Understanding what files to put and where, requires you to essentially RTFM and actually understand how the damn thing works. Who the hell one wants to do that, though? Similarly, most online tutorials I have seen dive in too deep, and try to show you how to create a functional site right away and it quickly becomes overwhelming. I’m not going to do that. I will show you how to create a very shitty, basic website in five minutes. A “Hello World” of Jekyll if you will.

First let’s grab Jekyll and prerequisites. Some of these are native extensions that have to be actually compiled on your system. This will be done automatically by the installer, but not all systems have the required compilers and header files. So first thing you want to do is to install the Ruby Dev Kit. If you are on Debian/Ubunty system you can just do:

sudo apt-get install ruby1.8-dev

If you are on Windows, grab the DevKit 7z file from the Ruby Installer website and then unzip it somewhere easy to find (eg. C:\RubyDevKit). Once you do that, here is how you install it:

cd \RubyDevKit
ruby dk.rb init
ruby dk.rb install

What does this do? It patches your Ruby installation, but honestly – we don’t care. It makes installation of Jekyll work. If you are inquisitive, you can read about the installation process here. Once you satisfied your curiosity, run the following command:

gem install jekyll

It will download and install Jekyll and all the prerequisites. Just so that we are clear, we are not counting the installation time into the 5 minutes time limit. If you want to time yourself, start your stopwatch now.

Let’s create a new directory for our website and call it mypage. Inside of that directory we create bunch of sub-directories like this:

mkdir mypage
cd mypage
touch _config.yml
mkdir _layouts
mkdir _posts
mkdir _site

Jekyll actually expects this folder structure to be present when you run it. The _layouts is where we are gonna put our template files – you know, HTML with holes in it. _posts is where we dump our content files – for example individual blog posts. _site is where Jekyll will dump out our “compiled” site. Easy enough so far, right?

Let’s make templates:

cd _layouts/
vim default.html

This file is going to be our main template with nice headers, footers, navigation sidebar and etc. Or rather would be, but we only have 5 minutes so instead I will make it this:

    
    
	    
    
    
	    {{ content }}
    
    

The {{ content }} tag is what tells Jekyll to create a hole in the layout that will be later populated by some content. Namely, by the stuff from your _posts directory. When you pull that data in, you sometimes will want to style it to your liking. Put it in a div, give it a nice heading, perhaps stick a creation date somewhere, etc. So let’s create another template for individual posts:

vim post.html

The contents are as follows:

    ---
    layout: default
    ---

    
{{ page.title }}

	    {{ content }}

The bizarre thing up top is so called YAML Front Matter. Jekyll will rip it off, and use it to figure out what to do with this file. Here we are basically saying “use the default template”. When you compile, Jekyll will take this and stick it into the “content hole” on the default template. Note that the post template has two “holes” of it’s own that will be populated by an actual content page which we are going to create next:

cd ..
cd _posts/
vim 2012-01-18-hello.markdown

There are two points of interests here:

1. The file name must start with a date in a YYYY-MM-DD format followed by a title. This is how you tell Jekyll when this post was published. It’s like that by design, to make processing fast and simple. Don’t question it. Just do it.
2. Yes, this is a markdown file. You can also use Textile, or plain HTML. It’s up to you. Jekyll is fine with either one of these. Using a non HTML markup language makes content creation slightly more streamlined as it really helps to separate content from presentation.

Here are the contents of my file:

    ---
    layout: post
    title: Hello
    ---

    Hello World!

Once again, we have some Front Matter up top. It tells Jekyll that what follows is to be wrapped up into the post template (which will then be wrapped up in default template) and allows you to specify an optional title attribute. If you scroll up to our post.html snippet, you will see this attribute accessed via {{ post.title }}. Neat, eh?

We are almost done. The last thing we need is a landing page:

cd ..
vim index.html

This is essentially going to be the “hello, welcome to my page” type thing. It’s up to you what you put here, but for the sake of simplicity I decided to make my front page to be an itemized list of all the published posts:

    ---
    layout: default
    title: Home
    ---

    

	    {% for post in site.posts %}
		
{{ post.title }} 
		({{ post.date | date_to_string}})
	    {% endfor %}
    

This ought to be more or less self explanatory. If you can’t read a generic for loop notation then I really can’t help you here. The last thing you want to do is to compile:

jekyll

Yep, that’s all you need to do. Actually, I recommend running this instead:

jekyll --server

It will create a mini-server on your machine, that you can access by going to http://localhost:4000 and inspect your creation.

That’s it. That’s all there is to it. You now have a fully functional Jekyll site. Mess around with it. Add another file in the _posts directory and see how it is linked on the front page. Better yet, grab a free CSS template and use it as your default.html (after adding the {{content}} tag inside) for an instant, gorgeous looking web page.

If you want something that look at least semi-presentable out of the box, you can check out my Simple Jekyll Site layout on Github. It is a very, very basic two column layout with minimalistic design that lends itself to easy extension. It is already formatted as a Jekyll site so all you need to do is to tweak a few of the links and deploy.

Seasoned Jekyll users, have you any advice for those just starting with it? Any gotchas to look out for, or life saving tips? Let us know in the comments.