sholsinger.com

This post documents my journey of migrating from WordPress to Jekyll. When you first start up Jekyll, you'll notice that you get this post entitled, "Welcome to Jekyll!" That page can be seen in the illustration below.

The sight of this welcome page is like that breath of fresh air when you're standing on top of a mountain with freshly fallen snow spread out in front of you and a board strapped to your feet. It's exhilirating. A clean slate with which to do and learn.

No Database

Jekyll builds internal data structures about your site. Here is an example of what this page looks like as a Ruby hash:

{
    "layout"=>"post",
    "title"=>"Welcome to Jekyll!",
    "date"=>2013-11-22 16:27:50 UTC,
    "categories"=>["play", "code"],
    "post_class"=>"welcome-to-jekyll",
    "stylesheets"=>["welcome-to-jekyll.css"],
    "url"=>"/2013/11/22/welcome-to-jekyll",
    "id"=>"/2013/11/22/welcome-to-jekyll",
    "next"=>nil,
    "previous"=>#Jekyll:Post @id="/2013/07/30/demandware-sublime-text-package",
    "tags"=>[],
    "path"=>"_posts/2013-11-22-welcome-to-jekyll.markdown",
    "content"=>"omitted for brevity's sake",
    "excerpt"=>"omitted for brevity's sake"
}

The best part about this is that the entire site goes into version control. So every thing that changes has a commit history. Also, with a static site, you don't have to worry about people using exploits in old FOSS code running in your blogging platform / CMS.

Generators

Posts are just files with datestamps in their filename. Textile, Markdown; whatever format you want! Jekyll creates a collection of the pages and posts and their front-matter metadata and then runs all of it's generators.

The best thing about generators is you can make your own. Want to create pages for every category? Go for it. Here's my category index generator. I think I got it from Octopress

module Jekyll

  class CategoryPage < Page
    def initialize(site, base, dir, category)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
      self.data['category'] = category

      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
      self.data['title'] = "#{category_title_prefix}#{category}"
    end
  end

  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      if site.layouts.key? 'category_index'
        dir = site.config['category_path'] || 'categories'
        site.categories.keys.each do |category|
          site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
        end
      end
    end
  end

end

Generators are what you would use to create new types of pages. Perhaps you want to list all the tags in the site and the posts that go with them. You could take that category index generator and modify it to build tag indexes instead. The sky is the limit!

Velocity & Portability

The fact that I got my category generator from Octopress brings up an excellent next point. The Jekyll ecosystem is exploding in many different directions, however most if not all of these directions are backward-compatible with Jekyll. So the plugins and generators written for things like Octopress can be used in your vanilla Jekyll setup.

You may also want to check out Jekyll Bootstrap which is now defunct but may still have helpful examples of what you can do with Jekyll.

Tools & Utilities

• Jekyll Debug Filter — Really helpful for figuring out the internal workings of Jekyll with super easy syntax:

  {{ page | debug}}

• Jekyll Image Tag — handles image resizing at generation time with pretty simple syntax:

  {% image large welcome-to-jekyll.png %}

That's all for now, but I'll try to keep adding things as I move forward with my migration from WordPress to Jekyll.