Why I use Jekyll for blogging

Posted on 2011-07-03

For several years I wante to write and tried many different platforms 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(install link for jekyll install 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:

---
layout: layout
---
<article class="post" role="main">
  <header>
    <section class="author">
    Posted by <a href="http://twitter.com/wikimatze" class="newwindow" title=""></a> on <time>Jul 03, 2011 </time>
    </section>
    <div class="clearer"></div>

  </header>
  
  <div class="clearer"></div>

  <footer>
  <section class="about-author">
  <h2>Discussion and Tweets</h2>
  <span class="about-author-image">
    <a href="https://twitter.com/wikimatze">
      <img src="http://en.gravatar.com/userimage/10525092/791987da4ba0ca49f1b8cc42bc7d4efb.png">
    </a>
  </span>
  <p>
    <strong>About the author:</strong> My name is Matthias Günther.
    This blog collects my thoughts about different topics as are my interests. I'm currently writing
    <a href="http://www.padrinorb.com/">Padrino book</a>, running <a href="http://www.vimberlin.de">vimberlin</a>, and being
    a <a href="http://railsgirlsberlin.de/">railsgirls-berlin</a> coach.

    <div class="clearer"></div>

    <div class="right">
  <a href="https://twitter.com/share" class="twitter-share-button" data-count="none" data-via="wikimatze">Tweet</a>
    <script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
  <a href="http://twitter.com/wikimatze" class="twitter-follow-button" data-show-count="false">Follow wikimatze</a>
    <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
</div>


    <div class="clearer"></div>


    <div class="clearer"></div>

  </p>
</section>

  </footer>
</article>

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

Creating a layout

Here is the main template for my blog.

<!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>
  <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  
    <title>Why I use Jekyll for blogging</title>
  
  <meta name="author" content="" />
  <meta name="description" content="Writings, talks and pictures by . Günther works at MyHammer, loves painting Warhammer figures, and enjoys making cakes." />
  <link rel="alternate" type="application/rss+xml" href="" />
  <meta name="viewport" content="width=device-width, maximum-scale=1.0" />
  <meta name="robots" content="noodp, nodyr" />
  <link rel="stylesheet" href="/css/stylesheets/base.css" type="text/css" media="screen, projection" />
  <link rel="stylesheet" href="/css/stylesheets/syntax.css" type="text/css" />
  <link rel="stylesheet" href="/css/stylesheets/print.css" type="text/css" media="print" />
  <link rel="shortcut icon" href="http://farm8.staticflickr.com/7078/7284507972_a7aa341781_t.jpg" type="image/x-icon" />
  <link rel="canonical" href="/why-i-use-jekyll-for-blogging.html" />
  <link href="" rel="alternate" title="Blog of " type="application/atom+xml" />
</head>

<body>
  <div id="site" class="round">
    <a href="/why-i-use-jekyll-for-blogging.html#top" id="top"></a>

    <header id="page-header" role="banner">
      <span id="sitetitle">
        <a href="/index.html">wikimatze</a>
      </span>
      
      <nav id="navigation">
        <ul>
          <li><a href="/about.html">about</a></li>
          <li><a href="/projects.html">projects</a></li>
          <li><a href="/contact.html">contact</a></li>
          <li><a href="/follow.html">follow</a></li>
          <li><a href="/blog.html">blog</a></li>
          <li><a href="/talks.html">talks</a></li>
          <li><a href="/books.html">books</a></li>
        </ul>
      </nav>
    </header>

    <div class="clearer"></div>

    <div id="ribbon">
      <a href="https://github.com/matthias-guenther" rel="me" target="_blank">Fork me on Github</a>
    </div>
    <div class="seperator"></div>
    <div class="clearer"></div>

  
    <h1>Why I use Jekyll for blogging</h1>
  
    

    <footer id="page-footer" role="contentinfo">
      <nav>
        &copy;2012 
        &bull;
        <a rel="nofollow" href="/why-i-use-jekyll-for-blogging.html#top">top</a>
        &bull;
        <a rel="nofollow" href="">RSS</a>
        &bull;
        <a rel="nofollow" href="/imprint.html">imprint</a>
        &bull;
        <a rel="nofollow" href="/colophon.html">colophon</a>
        &bull;
        <a rel="nofollow" href="/donate.html">surprise me</a>
        <span id="last-build">last build: 5-7-2013</span>
      </nav>
    </footer>

  </div>

  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>

  <!-- Add fancyBox -->
  <link rel="stylesheet" href="/js/fancybox/jquery.fancybox.css?v=2.0.6" type="text/css" media="screen" />
  <script type="text/javascript" src="/js/fancybox/jquery.fancybox.pack.js?v=2.0.6"></script>

  <!-- Optionaly add button and/or thumbnail helpers -->
  <link rel="stylesheet" href="/js/fancybox/helpers/jquery.fancybox-buttons.css?v=2.0.6" type="text/css" media="screen" />
  <script type="text/javascript" src="/js/fancybox/helpers/jquery.fancybox-buttons.js?v=2.0.6"></script>
  <script type="text/javascript">
    $(document).ready(function() {
        $(".fancybox").fancybox(
          {
          wrapCSS    : 'fancybox-custom',
          closeClick : true,

          helpers : {
            title : {
              type : 'inside'
            },
            overlay : {
              css : {
                'background-color' : '#eee'
              }
            }
          }
        });
     });
   </script>
</body>

I’m using 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 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.

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.