The Jekyll Experience

July 21, 2016


Preface

I’ve been building websites for more than a decade, you would think that by now I would have the absolutely best workflow for building a website, but alas, I am still learning and tweaking my workflow.

I recently wanted to build a simple blog for my site and wanted to avoid the bloat and maintenance of Wordpress,after consulting the oracles at Reddit, I went with Jekyll, a static website generator I haven’t used before, here’s my experience so far:

What,Why Jekyll ?

Jekyll Logo

If you haven’t used a static site generator, the big idea is that every time you make changes to your site files, your whole site gets rebuilt to reflect those changes, but unlike a CMS, you are mostly in charge of uploading your site to your server or host.

The biggest selling point is that you can include page and code variables and your file and folder structure works to make repetitive task easier, things like pagination, code snippets, menu bars, post lists etc,etc become a breeze; additionally, there is usually a template engine to help you import or make your own page templates.



There are so many out there, there is even a site that tracks them:

Top Open-Source Static Site Generators



I gave Myself 1 week to learn and implement this blog with the first on the list, Jekyll, that way if something went wrong or I didn’t like the experience I would just go onto the next one.

There will be Ruby,Gems and curses.

Installation Time: About 1 terminal session.

The Biggest pain point so far has been installing Jekyll,if you are looking for a simple App or executable, this is not it , Jekyll is written in Ruby, and as such it seems to prefer a Mac environment, ( haven’t tried it on Windows, but it seems possible) it also requires several dependencies and I had multiple conflicts that required hunting down fixes on Stack Overflow and running terminal updates and commands, so business as usual, just be aware you will have some terminal time, you like your terminal time don’t you ?

Learning Jekyll.

Learning Time: (15-30) 5 minute videos

Official Documentation : Jekyll’s Official Documentation

Great resource, but not very beginner friendly, if at first it seems inscrutable, fear not, this is your guy:

Thomas Bradley’s Jekyill’s Playlist

I went over Thomas’s excellent tutorials,which are both short and to the point, but got the gist of it halfway through and skimmed over the rest, if you’ve done any CMS or scripting development it will instantly click.

Github Integration.

Setup/Learning Time: 0-2 days

While you can use Jekyll without Github, you would be missing out on one of the coolest things ever, free and seamless github hosting and integration of your Jekyll project or blog, that’s right, after you setup your Jekyll site you can simply commit from your local build to your Github repo ( a special gh-pages branch ) and you are done .

If what I just said made no sense, you might want to learn and integrate Github version control into your workflow , here’s a painless introduction to Github:

GITHUB for NOOBS

Codepen & Jekyll.

So where does Codepen fit into this static website Github hosted Jekyll business ?

In my case, I wanted a very specific look for my blog posts inspired by Scrivener - an amazing writing tool, so I decided to make a couple of prototypes for my blog index and posts and then use them as templates for my Jekyll site, here they are:

The Index page:

See the Pen Bootstrap Blog Index Template by Eugenio - Keno - Leon (@k3no) on CodePen.

The posts Template:

See the Pen Bootstrap Blog Post Template by Eugenio - Keno - Leon (@k3no) on CodePen.



The final templates ( layouts & includes in Jekyll’s parlance) ended up a little different, but using Codepen for the initial sketch was not only a time saver, it was fun

Adapting the prototypes:

To give you an example of how Jekyll works, here is the Index file that generates this blog:

---
layout: default
title: K3no.com Fron End Web Development, UI,UX Design
---

<div class="row postIndex">
  <div class ="col-sm-1"></div>
  <div class ="col-sm-10">
    <br />
    <br />
    <h2 class="blogTitle"><b>Front End & Web Development</b></h2>
    <br />

    {% for post in site.posts %}

    <div class="list-group">
      <a href="{{ site.baseurl }}{{ post.url }}" class="list-group-item">
        <h4 class="pull-right"><i>{{ post.date | date: '%B %d, %Y' }}</i></h4>
        <h2 class="list-group-item-heading"><b>{{ post.title }}</b></h2>
        <p class="list-group-item-text">{{ post.excerpt }}</p>
      </a>
    </div>

    {% endfor %}

  </div>
  <div class ="col-sm-1"></div>
</div>



You might be wondering where is the rest of the document and what are those curly things, well, that’s how Jekyll works, the block up top is called Front Matter and allows you to specify a layout ( where most of the html resides) ,declare page variables and much more, the curly things are variables that work in tandem with the folder structure to allow you to say… go over all the posts in a folder and list their titles and create post pages, there is of course a lot more to it and this is not a tutorial, but hopefully you get the idea of how your files will look.

A typical Jekyll workflow.

  1. Open Github Desktop
  2. From Github open project in Terminal
  3. Start Jekyll in terminal
  4. From Github open the project in a text editor (I like atom) — Sounds like a lot of work, but takes about 10 seconds in practice —
  5. Write and Create posts ( The whole site gets recreated each time you save) and lets you know through the terminal if something went wrong.
  6. Preview the new pages or changes locally (in a browser on localhost:4000)
  7. Commit to Github pages and changes or posts are now live.

Final Impressions.

  • It took about a week to learn and make a small blog CMS in jekyll, your learning curve might be longer or shorter depending on your previous web development experience and other factors, due to it’s popularity and maturity, there are decent jekyll learning resources online.
  • I wish I had used Jekyll before.
  • Now I want to explore more static website generators.
  • Not sure I would recommend it to non technical users or leave an average client in charge of updating a Jekyll site.
  • A great almost bulletproof workflow with Codepen tests and Github integration.
  • Still room for improvement, live reload, and an easier setup & beginner documentation would be great, but if you are willing to put in a little effort it is a great web development tool to get into.



Drink Up !,

Keno

Jekyll Logo