JohnCromartie.com / How I Develop This Site

3 July 2020

When I decided to build a simple personal website, after considering hosted platforms like Medium and Squarespace, I looked at static site generators. The number of static site generators is staggering. There are currently 290 projects listed at staticgen.com. "Analysis paralysis" is a real thing.

After reading about the most popular tools, I tried Hugo, since I like the Go language. I spent a few hours learning the basics of Hugo and building a simple site with a custom theme. I soon realized my needs were just a tiny subset of what Hugo offered and that I could write a program to generate exactly what I wanted with just a little bit of code.

I ended up writing a small Clojure program that, like most static site generators, renders the home page of the site and a directory full of Markdown posts to an output directory.

I chose Hiccup for generating HTML from simple data structures, and markdown-clj for processing Markdown files. Clojure is espcially good at transforming sequential data structures, like turning a list of posts into a list of pages and HTML elements.

My deployment process is simple: lein run followed by aws s3 sync to a private S3 bucket served by CloudFront. Deployments take about 5 seconds. My AWS costs are less than a dollar per month.

According to cloc, the Hugo project consists of 1,415 source files and 150,069 lines of code, 98,998 of which are Go, with a few hundred lines of Python and Bash. At this time, my site generator consists of 5 files and 152 lines of code, 142 of which are Clojure.

If there is a problem rendering my website, it is likely to be in the few lines of code that I wrote rather than in the tens of thousands of lines of unfamiliar code in a tool like Hugo. Of course I could encounter a problem in a library that I rely on, but other static site generators tend to rely on even more libraries.

Choosing a static site generator tool is a daunting task. A mainstream static site generator is a good choice for a large website with a team of maintainers. However, if you want to build a simple website by yourself, try writing a simple program instead. It is a creative and rewarding project that frees you from conforming to other people's design decisions and gives you the control and flexibility to build exactly what you want, and nothing more.