Working with Jekyll

Ricochet works primarily on the Drupal and the Meteor website development platforms, but that doesn’t mean we can’t or won’t delve into other platforms when the project warrants it.

To meet the requirements of a recent project, a simple 4 page website, it was suggested that I spend an hour researching static website development systems Middleman and Jekyll and use one of those for development. We acknowledged that researching and learning a new system would add some overhead to the project, but in the end it proved to save me development time and headaches.

Before starting development I skimmed through the documentation for both Jekyll and Middleman, installed them and briefly tested them. What I was looking for was something that would be fast to deploy and contain easy to understand templating syntax. For the needs of this project Jekyll stood out as the winner, the documentation was easy to understand and the project was supported by Github — where the site is hosted now using Github’s “Pages” integration.

Disclaimer: Even though I’ve now completed a site using Jekyll don’t hold me to expert status: because of the simplicity of the project I didn’t need a ton of features, nor did I explore the full capability of Jekyll. Once I had achieved the functionality desired I was after I dove into development.

Installation of Jekyll

Installation was quick and easy (http://jekyllrb.com/docs/quickstart/), and the

$ jekyll serve --watch

functionality, which serves the site at localhost:4000 is a bonus. Many platforms now come with the capability to quickly and easily serve up the project locally without running a separate server such as MAMP, so this isn’t a unique feature, but it helps.

Front-matter

Front-matter is a feature that comes from YAML (http://yaml.org) which was new to me, but it didn’t take very long to learn how to utilize its powers. Besides defining the default variables for each page, I added my own custom variables to customizing the primary menu items and the background images for each page.

---
layout: default
title:  Welcome
link: Vineyard
background:
 - url: coastline.jpg
---

Templates

In Jekyll you can define unlimited page templates. I used one page template for the main pages and a second page template for pages that open in a lightbox. The template contains everything except the content — unlike a CMS, I don’t think you can define templates for a portion of the site, such as a sidebar.

Confusion over Development Files vs. Build files

Even though I had read through the documentation several times, what was unclear to me was the relationship between the template files, the build files (what was generated by the:

$ jekyll build

command) and the hosting environment.

Since all of our website projects live in a git repository (that’s how they are pulled into the production hosting environment) did I need to have a separate repo for the build files? Do I run

$ jekyll build

locally and then commit the generated files to a separate repository for the host?

If we were using a standard hosting environment, I think the answer would be to upload the generated site using something like sftp — there isn’t much purpose to putting it in a repo if your raw files are already in a repo because you can always rebuild and re-upload if your site files are lost.

Github Pages recognizes and builds the Jekyll site automatically. Because we are hosting on Github, I only needed to push my files in the master branch and Github takes care of the rest — you can leave the generated files out of your repo completely (this is recommended).

Conversion to Drupal

Eventually this will become a Drupal site so I wanted to make sure that this would plug into a Drupal template easily so we don’t spend a lot of time reworking things.

With the exception of content files, the completed site looks somewhat like a Drupal theme folder in its structure: it contains CSS, SASS, JS, images and template files. When it comes time to plug in to Drupal, I think it will be a simple copy and paste operation.

Automatically Generate Navigation

Because my site has only 4 pages, this wasn’t a requirement, but it was nice to have.

Following the instructions here I was able to create an automatically generated menu with active state. To exclude pages from the menu, set the link variable in the Front-matter of the specific page to “blank”.

Unfortunately I was unable to achieve the “sorted” functionality. Files are sorted by name in my example so if you need them in a specific order consider prepending numbers to your pages.

For reference: http://stackoverflow.com/questions/9053066/sorted-navigation-menu-with-jekyll-and-liquid

            

            {% assign sorted_pages = site.pages | sort: 'name' %}
            {% for node in sorted_pages %}
              {% if node.link != "blank" %}
              {{node.link}}
            {% endif %}
            {% endfor %}
            
          

Bonus

I really like the fact that when developing on Meteor, once I’ve hit the [save] button the site is updated with my changes. While I was setting up this site I stumbled across this post, which talks about how to accomplish the same type of functionality.

Follow the instructions to install

After you run:

$ jekyll serve --watch

open another terminal and run:

$ guard

If installed correctly your site running locally will automatically refresh when files are changed.