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:

    <html>
    <head>
	    <title>My Jekyll Test</title>
    </head>
    <body>
	    {{ content }}
    </body>
    </html>

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
    ---
 
    <h2>{{ page.title }}</h2>
 
	    {{ 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
    ---
 
    <ul>
	    {% for post in site.posts %}
		<li><a href="{{ post.url }}">{{ post.title }}</a> 
		({{ post.date | date_to_string}})</li>
	    {% endfor %}
    </ul>

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.

This entry was posted in programming and tagged . Bookmark the permalink.



5 Responses to Building your first Jekyll site in 5 minutes

  1. Marco Campos PORTUGAL Google Chrome Windows says:

    Check out Octopress. Like it’s says on the website: “Octopress is an obsessively designed framework for Jekyll blogging. It’s easy to configure and easy to deploy.”

    Reply  |  Quote
  2. astine UNITED STATES Mozilla Firefox Windows says:

    The thing about static site generators like Jekyll is that there are a lot of them. Jekyll is only the most popular, (Mostly because of its association with Github.) Here’s a list of 32 of them and I know of at least one that’s not on that list. I use nanoc for my own site. I like it better than Jekyll because it exposes its innards more and lets me use ERB rather than Liquid.

    One thing you want to do no matter which site generator you use is to place your source files in version control. This lets you easily keep a backup of your site and edit it as if it were local no matter where you are. It also allows you to rollback changes much more easily. This is one of the chief benefits of using a static site generator instead of a database backed system like WordPress or Drupal.

    Also, the easiest way to comments is to just use something like Disqus for them.

    Reply  |  Quote
  3. I love Jekyll and use it for my own site, hosted by Github.

    Another tip: Jekyll can automatically regenerate the site when a file changes, with --auto. Most of the time when editing a post I have Jekyll running with automatic regeneration.

    I used to use the --server option, but the webserver provided by Jekyll isn’t very good. It can’t properly serve up HTML5 video files, for example. Right now I have Emacs do that job instead.

    Also, Jekyll is very slooooooooow. My website takes about 2 minutes for my computer to compile from scratch, and almost as long for regeneration. This can make it a pain to make small CSS tweaks. I usually end up doing that in _site and copying it out when I’m happy. If you converted to Jekyll, I can’t imagine how long it would take to generate a site like this one, since you have probably thousands of posts. I only have under 167 posts.

    As for getting started, when I moved from blosxom to Jekyll earlier this year, all I really had to do was change the template markers to Liquid’s (Jekyll’s) syntax. So I had already gone through the initial setup years ago.

    Reply  |  Quote
  4. Luke Maciak UNITED STATES Mozilla Firefox Windows Terminalist says:

    @ Marco Campos:

    Thank you sir. I will check it out.

    @ astine:

    Wow, nice list. I haven’t even heard of most of these. Thanks.

    @ Chris Wellons:

    Yeah, this site would probably take ages to compile. There ought to be an –incremental flag or something – that only processes files that have changed since last edit. Then gain, small edits can have cascading results due to the way Jekyll generates these pages, so that probably wouldn’t work.

    Also, this is yet another example how Emacs is a fucking operating system. :P

    Reply  |  Quote
  5. Richard Google Chrome Mac OS says:

    Great post Luke. I’ve created this thing called muffin which is a jekyll template with bootstrap, sass, and grunt. It makes it super simple to set up a jekyll site. Check it out.
    http://richbray.me/muffin/

    Reply  |  Quote

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>