For several years I wanted to write and tried many different plattforms like wordpress, blogger, or tumblr. The main problem which kept me away from writing was just the fact, that every time I want to write I just had to do it in a new environment and not in my favorite editor vim. Every system gives me the freedom to extend it in several ways but in the end it didn’t provide me the freedom to change every tiny piece I want. With jekyll I can use my favorite text editor and it really “turned me into a text monster”. This description sounds like a holy grail, but let me explain its abilities in the following sections.

What jekyll is

Jekyll is a static site generator written in ruby. It generates static html pages. The page is presented through several templates and then fires the whole site, were articles are written in a text markup language like Textile or Markdown, through the liquid converters to generate fully generated compiled website. Don’t think that it will be so easy for you to do it. First of all you have to learn either Textile or Markdown. I chose textile for writing my posts because I use Markdown to create the README files for my github account.

Setting up the environment

You need to have a valid ruby and ruby gems installation on your machine. A simple gem install jekyll will install the following gems:

• directory_watcher (gives a list of files which change in some intervals)
• liquid (rendering templates in a safe manner)
• open4 (creates a child process to handle pid, stdout, etc.)
• maruku (Markdown interpreter)
• classifier (is a Bayes implementation and can be used semantic indexing like to display related post – this mechanism is used in machine learning)

To get nice syntax highlighting for your code you have to install pygments via sudo apt-get install python-pygments on Ubuntu/Debian. On the install page you can get more information about how to setup jekyll.

The directories and styles

Here is the basic layout of a typical jekyll project:

• _includes: Small snippets which can be used in every place of the page.
• _layouts: You can define layouts for post entries and the general default layout. Posts can have the special Yaml Front Matter.
• _posts: Contains all posts in your specified markup language
• _config.yml: Is a file to store configuration data like the styling of the urls, or some global variables. It is also possible to define own variables which can be used as global things on other pages.

Other files can just put on the root directory like an atom.xml file (for RSS feed) or 404.html page. For example my post.html has the following layout:

The lines between --- mark a special Yaml Front Matter file. This block is treated as a special block in jekyll and can contain different components. The { {content} } stands for the content of a post entry.

Creating a layout

Here is the main template for my blog.

I used the meta-language Sass to create my CSS. There is one problem with Sass: You have to compile it every time you made a change. Fortunately, there is the compass gem which always compiles my sass file when I change it. When I build my page I started with compass watch css/ & a command to automate Sass building. This is very handy when changing the layout.

Static webpages – how to include dynamic content

Jekyll only creates static webpages but with the help of Javascript it is possible to add a Disqus comment platform. You just have to create an account and then use the following snippet:

It is best to put this piece of code in an extra file under your _includes directory and then add it in your template for posts. Now the comment function is available in all your posts.

Deployment

There is a bunch of deployment strategies: rsync, ftp, Rack-Jekyll (deploy on Heroku, EC2, etc.). I prefer ftp (with the glynn) because it was easy to install and worked great with my server configuration in my _config.yml.

Conclusion

Just look on other pages what is possible with Jekyll. You can learn many new things by looking at other jekyll blogs and copy what you need. I love to write a little bit and after I finished an article just perform rake deploy to upload my blog.