Forwardslash /

TAGS: code

Next-Gen Static Sites

Notes on Jekyll, Github Pages and

Forwardslash is beginning its life in a cutting-edge-for-2015 way: hosted on Github Pages and built with Jekyll. Here are my notes from the process. As I’d like to do with the rest of this blog, I’m going to try to make it of interest to people who aren’t technologists as well as those who are - so following is an overview of the technology as well as a quick-start guide.

##Next-Gen Static Sites

The simplicity of a static site is very attractive. It’s just HTML files, so you can host it anywhere, best of all on a blazing-fast, dirt-cheap CDN like Amazon S3. WordPress or another CMS has a database, which complicates hosting, especially when keeping things in sync across local, staging and production environments, and slows things down since webpages are assembled on the fly as people visit the site.

Static site generators have actually been around since the early web. So what is new about what I’m calling “next-gen static sites”?

First, the generators: Jekyll and similar tools run without a database and are ‘text-transformation engines’ running over a set of files you’ve created. They’re more lightweight than web frameworks like Rails or traditional CMSs like WordPress or Drupal, but offer some of the same power and convenience with the advantage of simplicity and flexibility.

Second, the ascendance of version control: with Github, it’s much easier than it used to be to keep everything in version control and use a version control system to deploy your website.

Third, increasing sophistication on the client side: static sites have their limitations, but advances in web browsers, JavaScript and CSS, and accompanying libraries let you get more out of an HTML page, and work around some of those limitations.

There’s also a fourth trend that’s useful here: the rise of web services and APIs to help with things like audio, video, and other advanced functionality beyond serving content.

The icing on the cake is that Github has built in a system for hosting static sites built with Jekyll for free. Called Github Pages, it’s a streamlined, cost effective way to deploy if you can make it work for you.

##Ready for Prime Time?

As a long-time WordPress developer, but even longer-time HTML enthusiast (my first sites were hand-coded HTML in the late 90’s) I was intrigued as soon as I heard about Jekyll, the static-site generator built with Ruby. I also had some skepticism: I worked a lot with Movable Type, a not-hip, not-new static site generator with some problems I won’t elaborate on here.

I was motivated to try this path for client sites when I read about the work Development Seed is doing building CMS-free websites. Like them, I’ve spent a lot of time wrestling with a large CMS codebase and a leaner approach sounded really refreshing. Development Seed even employed this site-building philosophy on the new They made a very compelling argument for doing next-gen static sites, which I’m partially reiterating here.

The biggest deal-breaker for clients is Jekyll’s lack of an administrative interface for updating content. You can’t expect most people to blog using Markdown and then fire off commands in Git to update their site. Development Seed proposed an innovative solution for this: Prose, a tool for editing content hosted on Github.

Prose was very promising, and it still could be. But as of this writing in early 2015, I have to warn the reader that it is plagued with bugs and it appears to no longer be in active development. My takeaway is that Jekyll and Github Pages are awesome site creation tools, but still only for technical users or those willing to get up the learning curve.

Getting Started

Convinced already? Ok, here you go. Getting started with Github Pages is as painless as it gets - Github has an excellent starter guide. It walks you through a ‘hello world’ getting your first changes up in seconds, which is very gratifying.

Then, the Using Jekyll With Pages guide gives you some important-seeming tips on making your local setup match Github’s which it’s probably best to follow. You’ll probably want to use your own domain name, too - covered here - just create a CNAME file in the gh-pages branch as Github instructs and then point your domain’s A records to Github.

Fresh Jekyll

The Jekyll site has nice documentation and will be your go-to. For a quick-start Jekyll instance, Poole is a decent place to start - a skeleton setup with just enough in place to get up and running but nothing much to undo or redo.

Blogger Joshua Lande made a nice walkthrough with some customizations. I’ll suggest another one: a code snippet to get the previous / next navigation on individual posts (cutting and pasting the one from Poole’s homepage won’t work). I shared it as a Gist here.

Deploying Changes

The main thing to remember with hosting on Github Pages is you have to have the changes in the gh-pages branch for them to be reflected on the live site.

So if you’re working locally and have some changes on your master branch, you’d do this:

git checkout gh-pages
git merge master
git push origin gh-pages

Github Pages regenerates the site every time it gets a new commit in the gh-pages branch. It can take a minute for the changes to reflect, but usually it’s pretty snappy.

Using Prose (At Your Own Risk)

So the dream of Prose (kept alive in a lot of blog posts from 2012 and 2013 when it still seemed like bug fixes were happening) is to give you an easy way to update things - on the go, from the cloud, without touching the command line. It really is super cool, but currently is a bit frustrating - not enough to be unusable, but enough to keep me from recommending it to clients without a big grain of salt. If you still want try it out and see for yourself, keep the following in mind.

Every change is a commit. In the Prose editing window, you must make sure your ‘changes to save’ reflect the changes you just made. Sometimes they don’t. You must make sure they do - otherwise, you’ll lose them. This is my second time writing this blog, and I was pounding my desk after losing a draft. Keep in mind, I didn’t notice this bug occurring again, and it could be because I tried to rename the file and save changes to that file at once. The takeaway: Make sure the changes about to be commited reflect what you just did!

Are you in the right branch? So you just made a change to the site, but where is it? You have to remember to get your changes into the gh-pages branch for them to be reflected on the live site. But in addition to that, Prose doesn’t remember what branch you’re working in - so every time you click around, it switches back to the master branch, and you accidentally end up making commits there. The best hack to deal with this is probably to just automatically sync master and the Github Pages branch, using this method or one of these.

It’s All About the Configuration To get the most out of Prose, direct your attention right away to the configuration options. You can set up all sorts of metadata in beautiful-looking forms (subheading, title, author twitter, etc) which would make for great handoff of a site to less-technical clients. I didn’t encounter any bugs here, but there seem to be outstanding issues when you check out the open ones.

Media Uploading is Broken At the time of this writing, it’s the biggest deal-breaker. And it’s a bad one. Attempting to upload media yields unpredictable results and various kinds of problems, and configuration doesn’t work as the documents indicate.

Jekyll Beyond Github Pages

Hosting on Github Pages is great because it’s free (or cheap, if you’re a paying Github subscriber), and effortless. The limitation is that Github prevents you from using Jekyll plugins for safety and simplicity’s sake. If you’re only publishing content and that’s it, you probably don’t need to use plugins, especially with JavaScript at your disposal.

A quick note on the confusion around tags and categories. Jekyll does support them out of the box, but you have to do some manual configuration - one approach outlined here - which might be annoying. If you want tags and categories handled automatically then you would require plugins to generate tag and category landing pages with a plugin.

Other examples of uses for Jekyll plugins are generating archives, a sitemap or redirects; adding search or rss; converting LESS to CSS or CoffeeScript to JavaScript; adding word count and a reading time estimate; pulling Tweets from the Twitter API; generating thumbnails from a directory and displaying them; even rendering ASCII art into png images. You can find all these and more on the Jekyll plugins page.

So - what about those situations where you want to use one of these plugins or write your own Ruby code to supplement Jekyll? You can always just do this by building your site locally and sending the files to your hosting environment, using something like S3 website. And Development Seed made a tool for called Jekyll-hook, which very cool because you could deploy to S3 or another CDN with the same easy workflow as Github Pages.

In Summary

You don’t have to look hard on the Internet to find glowing praise for Jekyll, and I share the enthusiasm. Developers love it, and I think the combination of simplicity and flexibility is what makes it so nice.

But it remains a tool / toy for hackers, and as long as Prose remains half-baked, isn’t really ready to hand off to clients to maintain for themselves. It’s a hands-on solution, and for many websites this is totally fine.

I do think next-gen static sites are here to stay and are going to improve. What if Github picked up where Prose left off by building a kick-ass editing suite of their own? I only recently noticed that they already have a “Zen mode” for fullscreen editing of files.

Expanding on this could open a whole new line of business for Github, and introduce the wonders of version control to writers, web producers, editors, journalists and the like. That would be a cool thing.

More Reading

The Power and Potential of Github Pages - Introduces some of the cool things you can do as well as the limitations.

Prose Thread on Hacker News - Read and beware if you want to use it. Then check out the open bugs on Github here for another reality check.

Liquid for Designers - Liquid is the templating language Jekyll uses - it’s a Ruby gem developed by Shopify. In reality this is more developer-friendly than designer-friendly, but it’s the nicest concise documentation of Liquid I’ve seen.

TAGS: code