Build Your Site with Jekyll

by Ostatic Staff - Jul. 12, 2010

I host my personal blog on Github using Jekyll, a powerful command line blogging tool and content management system. Jekyll makes it easy to manage blog posts, pages, and media like movies and pictures, all without needing an interpreted language like PHP or a database to run the backend. Jekyll outputs the entire site as static HTML files, ready to be uploaded to any web server, or committed to Github's Pages.

To install Jekyll, first make sure you have ruby and rubygems installed and working. Then, installing Jekyll should be as easy as sudo gem install jekyll. Jekyll relies on a specific file and directory naming scheme. To get started on your first Jekyll site, create a directory with the name of the site, and then create two directories inside of it named _layouts and _posts.

_layouts This directory contains the templates for the HTML that Jekyll will produce. Create two new files named default.html and post.html. The default.html file will contain the default “theme” of the site. To get started, all you need is to add some basic HTML tags:

    <html>
    <head>
    </head>
    <body>
    	{{ content }}

    </body>
    </html>

The content tag inside of the double brackets is where Jekyll will be putting the content from the other files we'll be giving it. In the second file, post.html, we will tell Jekyll that we want to use the default.html file for our theme, but we want a little different layout:

post.html

    ---
    layout: default
    ---

    <h2>{{ page.title }}</h2>
    
      	{{ content }}

Jekyll first replaces {{ content }} with the post, and then replaces {{ content }} in default.html with the entire new contents of post.html.

To understand this process a little better, let's create our first blog post as a markdown formatted text file in the _posts directory. Jekyll requires that all posts be named using the format date.title.markup language, as in 2010-07-11-hello.markdown. In this file, put the following text:

2010-07-11-hello.markdown

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

    Hello World!

Here we are telling Jekyll to use the post.html file as the template for this blog post, which in turn uses default.html as it's template. If we now go back to the site directory and run jekyll, you may get some warnings on the screen, and then you'll see that Jekyll has created a new directory named _site. This directory contains the static HTML files good to be uploaded to any web server. It is your complete site, as Jekyll understands it to be. Our hello.html file will be buried in a directory structure that looks like /2010/07/11/hello.html, and should have contents that look like this:

hello.html

    <html>

    <head>

    </head>

    <body>

    	<h2>Hello</h2>    
    
    	<p>Hello World!</p>
    
      </body>

    </html>

Jekyll creates a single page for each blog post. To tie it all together, a few more files are needed in the root of the site directory.

Create three files named index.html, archive.html, and _config.yml.

index.html

    ---
    layout: default
    title: Home
    ---
    
    <div id="posts">

    	{% for post in site.posts offset: 0 limit: 10 %}
          <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
          {{ post.date | date_to_string }}
           {{ post.content }}

        {% endfor %}
    
    </div>

archive.html

    ---
    layout: default
    title: Archive
    ---

    <h2>Archive</h2>

    <div id="post_links">
    	<ul>
    	{% for post in site.posts %}
    		<li><span>{{ post.date | date_to_string }}</span>  <a href="{{ post.url }}">{{ post.title }}</a></li>
    		{% endfor %}
    	</ul>
    </div>

_config.yml

    ---
    permalink: /:month-:day-:year/:title.html

The index.html file will pull the most recent 10 posts and add them to the home page. The archive.html file will create links to all posts in the site. The third file, _config.yml is used by Jekyll to set it's configurations, and is parsed before any other file. There is a list of available configuration options here.

The last step in building the site is to test it all locally by running jekyll --server, and then browsing to http://localhost:4000. Jekyll will build the new site, and start it's own web server using the _site directory as the document root. You should be able to browse from the home page to the hello.html page. Since we didn't add any navigation, you'll have to type http://localhost:4000/archive.html to see the archive.html page.

At this point, the core Jekyll engine is basically finished, and the site look and feel is ready to be designed. Jekyll gives you total control over your site, and adds the benefits of a simple deployment. If you are serious about blogging, Jekyll may be just the thing for you.

Build Your Site with Jekyll

Browse Other Topics