Technology stack for a static web site

---

Update

This post is out of date. If you are interested in generating static web sites, have a look at JAMstack, a great resource with plenty of pointers to recent technologies that will help you do so. This field has exploded since I wrote the post. Having said that, Jekyll is still going strong.

---

I have written a couple of web Content Management Systems and used several others. Typically, a CMS pours content stored in a database into templates that ensure a consistent look-and-feel. But when I set out to renew the web site advertising my consultancy services, I didn't want to go with the database paradigm as there is no dynamic content to speak of, so why add moving parts unnecessarily? This blog describes the technology stack I ended up with.

The template idea is good as you do not want to maintain duplicated boiler plate content such as menu's, headers and footers. So you not only need a templating language, but also a tool that takes content and templates as input and outputs HTML pages. In other words, this allows you to generate a static site whenever you add or update content. Apparently this meme started in 2008, with a tool called Jekyll, developed by one of the founders of GitHub. Jekyll is still under active development and continues to be a popular choice among web site developers. In fact, while there are many static site generators these days - cited in the definitive listing, for example - there is no clear contender.

So I went with Jekyll. Interestingly, choosing Jekyll as the site generator, also allows the site to be hosted by GitHub for free, which is a pretty good deal. However, there are some annoying limitations, chiefly they will only serve custom domains over HTTP, not HTTPS. Choosing Jekyll restricts the choices of templating languages to exactly one: Liquid. Liquid can in principle be embedded in any document format, such as HTML, XML or plain text email, but in the context of Jekyll, templates must be written in HTML interspersed with Liquid code. Incidentally, Jekyll uses the term 'layout' rather than 'template'.

I don't like writing HTML much as it is rather verbose. Unfortunately, I had no choice when developing Jekyll layouts. For the content, on the other hand, Markdown, a lightweight markup language, is a welcome alternative. However, Markdown comes in various flavors and there are many different, not entirely compatible, processors. Jekyll's default is kramdown. This is also the only HTML renderer supported if you wish to use GitHub hosting, AKA GitHub Pages.

Jekyll, Liquid and kramdown will not help with styling. If, like me, you do not want to write too much HTML by hand, you will most certainly abhor CSS. Yet, after the mobile revolution responsiveness is a de facto requirement, thereby making modern web sites even more reliant on CSS. An HTML/CSS/JavaScript framework such as Bootstrap does not make CSS entirely transparant, but it does ease the pain somewhat, especially when used in conjunction with a CSS pre-processor such as Sass or Less. Jekyll only supports Sass at present and hence forces the choice.

While versioning is awkward when using a database-backed CMS, it is entirely natural if you generate your site from templates and content files. That surely has to be a good thing. GitHub has become my default choice for version control. It also comes bundled with a number of other functionalities I also use. I already mentioned hosting. Then there is CI - Continuous Integration. Most CI tools have the ability to detect when you push new code to GitHub. This triggers the tests, analyses, builds, deploys you configure to run. I picked Travis because this is the tool the Jekyll docs discuss, but I am pretty sure that using other CI tools would not be difficult either.

Deployment is trivial if your site is hosted by GitHub Pages: pushing new code or content triggers the site generator. But, if you decide to move the site to somewhere else, for example because you want to serve it over HTTPS, getting Travis to deploy remotely should not be too difficult.