Getting Started With Jekyll
I took at look at Toby Di Pasquale’s website tonight and it inspired me to get around to sprucing up my own site.
Toby used Jekyll, a site generation and maintenance. Jekyll allows you to maintain your site using liquid (a text based templating tool), Yaml (for configuration) and Markdown (a simplified wiki-ish style markup language). Jekyll is a bit different from dynamic Blogging or publishing platforms like WordPress in that it intentionally generates your site as static content. Most of the other publishing platforms dynamically generate their content at the time the page is requested by the browser.
Jekyll allows you to refactor your content, still allowing you to use templates and simplified markup, while allowing your site to be completely static. This means you can deploy your site (or blog) to servers where you only have a web-server and no application software – it also means that your site will perform as well as your web-server can serve up static content, which is about as fast as you can get.
Setting the site up with Jekyll took only a few minutes…tweaking the css for the site and adding in some basic content took me a few hours.
Installation
You will need Ruby installed along with RubyGems. You will not need Ruby on Rails. Once Ruby and Gem are set up, follow the remaining instructions in the installation guide. A good place to start is by cloning one of the example sites:
kyle@asymmetrical-view ~/projects$ git clone git://github.com/mojombo/mojombo.github.com.gitThis will give you a point of reference for creating your own site. I made a directory and am using "git"h:ttp://git-scm.com/ to version my site.
Create your _config.yml
I initially had an incomplete `_config.yml` when I first tried to run Jekyll and it raised an exception. Start with the downloaded example or use mine:
destination: ./_site
auto: false
lsi: false
server_port: 4000
pygments: true
markdown: maruku
permalink: date
maruku:
use_tex: false
use_divs: false
png_dir: images/latex
png_url: /images/latex
Directory Structure
I created a sub-directory for each of the major areas in the site (posts, projects, contact, talks and about), a directory for the ‘blog’ posts (_posts) and for the layouts.
./site/_posts/2000-05-14-starting-with-jekyll.textile ./site/projects/index.html ./site/index.html ./site/contact/index.html ./site/css/style.css ./site/_layouts/post.html ./site/_layouts/default.html ./site/_config.yml ./site/about/index.html
Set up a Layout
In the examples you’ll see a layout file in _layouts/default.html
The layouts are your page templates. The template has the surrounding portion of the HTML page, with an inner yield block for the actual page content:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en-us">
<head>
...
<div class="content">
<div style="margin-left: 22%;">
{ { content } }
</div>
</div>
...
</body>
</html>
Then make use of your layout, for example in my ./site/index.html, I have a Yaml front matter that specifies the layout and the page title.
---
layout: default
title: Seeking No Barriers To Abstraction
---
<div class="index-body">
<h1>Welcome to Asymmetrical View</h1>
<p>
This is the home site of Kyle Burton on the Internet.
</p>
<h1>Recent Posts</h1>
<ul class="posts">
{ %% for post in site.posts limit:5 %% }
<li><span>{ { post.date | date_to_string } }</span> » <a href="{ { post.url } }">{ { post.title } }</a></li>
{ %% endfor %% }
</ul>
</div>
Creating Posts
My posts are all in textile (markdown) format, using a similar technique as with the html files they have a front matter section and then some main content in the markup:
---
layout: post
title: Getting Started With Jekyll
---
h1. { { page.title } }
I took at look at <a href="http://cbcg.net/">Toby Di Pasquale's website</a> tonight and it inspired me to get around to sprucing up my own site.
Building and Testing Your Site
To build out your site, just run jekyll. You can also run it in a simple server mode in which it will attempt to recognize when you change files (via their last modification time) and rebuild the effected portions of your site. One thing to keep in mind is that when you run jekyll with --auto it will not report on exceptions as robustly as it will when only invoked to perform teh build. The workflow I use involves perdiocally restarting the jekyll server and removing the site build directory:
mortis@kburton-lin ~/personal/projects/this-blog/site[this-blog*]$ rm -rf _site/ && jekyll --auto --server 4001
When I stop seeing my changes reflected in the site I’ll CTRL-C Jekyl and re-run that command.
Conclusion
Installing and learning Jekyll was easy and it provides me with a much lighter weight process for maintaining my personal web site.