I’m Paul Herron and I’m a web developer. I build online applications
with tools like CakePHP and jQuery.

Blogging with Jekyll: Static sites without the hassle

by Paul Herron on 25 January 2014

I just switched this website over to use Jekyll, the static website generator.

I've tried various approaches to managing my site content over the years. On one end of the scale, which I'll label "big and heavy", I used to run a custom content management system in CakePHP that had a MySQL database, an admin panel, user accounts, a WYSIWYG editor and all that stuff. It worked OK but this kind of "big functionality" doesn't come for free. Making sure your database backups are working properly, migrating your site to a new server if you ever change web hosts, keeping up-to-date with software versions in the hope you don't get your site compromised, trying to get your WYSIWYG editor to not chew up the formatting on your code snippets; all of these headaches can add up to make it feel like using and maintaining the system is as much effort as actually writing the content.

On the other end of the scale, I recently enjoyed going back to basics and converting my site to plain old static HTML. It's a great feeling being able to update the site by doing a quick edit, then saving and deploying the changes via Git. No logins, no admin panel interfaces getting in the way, just your favourite text editor and a version control system. But the static HTML approach only really works well for a single-page site. As soon as you try to get multiple pages in there – as I did when I started blogging again – things get laborious. You end up manually duplicating your site header and footer into every page, or having to write the title of your new blog post multiple times: once in the post itself, once in the blog listing page, maybe elsewhere. And then once you've duplicated that content you spot the typo that means you have to repeat the process. You probably won't bother with things like a sitemap.xml file because that means even more laborious duplication of content, and that's the way madness lies. I did use a little bit of automation to ease the process, so for example I would write my blog posts in Markdown and I had a couple of mappings set up in Vim to automatically export that to HTML and wrap it in my site's header and footer. It was far from perfect though, and thought that I as a human was having to process things manually that a computer could be doing is abhorrent.

Jekyll occupies the perfect middle ground between these two extremes. You get the joy of publishing content simply, by editing an HTML file or writing a blog post as a plain text file. But you also know that Jekyll is watching over your work and willing to step in right before things get messy: it compiles your templates and Markdown files into a static site automatically so you never again have to experience the drudgery of maintaining static HTML.

Here are some smart things it does:

Very quick start

It's very quick to get going with. As they suggest on the Jekyll homepage:

gem install jekyll
jekyll new awesome-site
cd my-awesome-site

It's then worth starting the Jekyll server in "auto-regeneration" mode, which will watch your files and recompile the site if anything changes:

jekyll serve --watch

The site should then be accessible at http://localhost:4000.

What's it doing?

The gist of it is, everything in my-awesome-site gets bundled into a static website and copied into the _site directory. To create that static bundle, Jekyll does a few things:

If you're already maintaining your site as static HTML files, it's really quick to convert it into a Jekyll site. For example, my old static site had a simple index.html page with some info about me, followed by a listing of recent blog posts. It was just a matter of dropping that file (and its accompanying CSS and JS files) into the Jekyll directory, and replacing the hardcoded listing of blog posts with something dynamic:

<ul>
    {% for post in site.posts %}
    <li>
        <a href="{{ post.url }}">
            <h3>{{ post.title }}</h3>
            <p class="meta">Posted {{ post.date | date_to_long_string }}</p>
            <p>{{ post.excerpt }}</p>
        </a>
    </li>
    {% endfor %}
</ul>

All that information about the blog posts was fetched automatically from the markdown files found in the _posts directory.

Deploying it

Part of the appeal of using Jekyll is that because you end up with a static HTML site, there's no need to have any special software running on the server. So to deploy the site you only need to get these static files onto the server. You may already have your Jekyll site under version control with Git, and that makes it easy to pull your updates live.

The way I did this was to edit the .gitignore file that Jekyll generates automatically, choosing to unignore the _site directory. I'm happy to commit the compiled site alongside my changes to the overall project.

Making it live is then just a matter of cloning the entire repo onto the server and pointing the server at the _site directory. In my case on Nginx that looks like:

server {
    listen 80;
    server_name paulherron.com;
    root /home/www/paulherron/_site;
}

Back to homepage

Next: