Building mitsake

2012-02-25

To start off my posts here I thought I'd document the process I went through in setting up this site. If nothing else, it'll be handy for me to refer to if I need to jog my memory later on.

I've been working on mitsake in some form for a few years but it's only now that anything has actually gone online. Procrastination is the main culprit, but I've also been trying to work out what to use to build the site. Over that time I've tried out Jekyll, Nesta and Octopress and liked all of them in different ways. Despite this, I eventually decided to go back to Jekyll for a few reasons:

Given the low-key plan I have for the site, static pages seemed a better fit than something running a dynamic CMS.
I like writing in HTML, CSS and Markdown and since I already know them, designing the site and writing posts didn't require me to learn anything else.
I wanted to be able to make a simple design for the site myself. While both Nesta and Octopress have great themes available, I found editing them more difficult than building one from scratch.
I've been interested in learning Ruby for a while. Since Jekyll's written in Ruby, extending it gives me a bit of practice.

Setting up Jekyll

Update (16 August 2018): This modification has been obsolete for ages now - Jekyll includes this behaviour by default.

Rather than write yet another post on how to get started with Jekyll, I thought I'd just detail the few small things I've done differently. If you are interested in setting up and configuring Jekyll though, there's a tonne of articles and other information available in the Jekyll documentation. So far I've only made one small addition to the default setup which is the introduction of a 'Read more →' button for longer posts on the home page. While it did require a plugin, I was fortunate enough to find code for something similar in a post by Kjetil Valle. This is what I put into _plugins/preview.rb:

module Liquid
    module ExtendedFilters
        def preview(text, delimiter = '<!-- end preview -->')
            text.split(delimiter)[0]
        end
    end
Liquid::Template.register_filter(ExtendedFilters)
end

This is backed up by some Liquid markup in my site's index.html which looks for the HTML comment  in the posts that are listed on the home page. If it's there, the post is run through the preview filter and cut at the point the comment appears.

{% if post.content contains '<!-- end preview -->' %}
    {{ post.content | preview }}
    <p><a href="{{ post.url }}">Read more &rarr;</a></p>
{% else %}
    {{ post.content }}
{% endif %}

NearlyFreeSpeech and deployment

Like choosing Jekyll, it took me a while before I decided on NearlyFreeSpeech as my host. Although both Heroku and GitHub Pages look like good free options for hosting Jekyll sites, I decided to go with NearlyFreeSpeech as it meant I could do domain registration, DNS and hosting all at the same place. I've also been able to learn a lot as their target market is people who don't mind getting hands-on with server administration. Most of the information I've needed has been covered in their extensive FAQ/documentation but since most of their setup uses standard Unix/Linux command-line tools, there's plenty of other places to look too.

Since NearlyFreeSpeech offers SSH, deployment is easy. One option that seems common on is to host a remote Git repository with a post-recieve hook that uses Jekyll to regenerate the site each time a commit is made. Although I'm planning to use this method in the future, for now I'm just using rsync over SSH. Although it's pretty straightforward, I found this page on Simon Pascal Klein's blog quite useful.

Design

As with my plan for the site in general, I only had a few goals for the design. I obviously wanted it to be reasonably nice to look at but I also wanted the site to remain readable if someone were to read it without the stylesheet or with a device that doesn't use visual stylesheets such as a screen reader. Of course, for 99% of people this isn't an issue but I like the idea of keeping the web as accessible as possible. If you'd like to see what I'm getting at, you can check out the unstyled version of this article.

I think that's everything I've set up so far. I do have plans to add extra features such as an RSS feed but I'll probably document them as they're added.