I built a static site generator

I built a static site generator

Well, a proof of concept for one, at least. I've been thinking of implementing one for a long time, after using multiple generators for this website and I finally did it.


Most often the answer to this question in general is that I wanted to know how it's done, and that's what first drew me in to try this out. Having used Hugo in the past, it immediately sparked my curiosity on how HTML was generated from simple markdown files. Generating HTML from template files is interesting enough, but I was really drawn into how from there website generators can create navigation between pages, resolve asset links, etc.

Recently we've seen the rise of so called Jamstack websites, which seem like the future for certain types of web applications, but a golden use case are blogs and small publications where content is static. If you really think about it, there's no point in renting a cloud server and hosting something like WordPress or Ghost when you can have a git repository run a build script that puts the static content on a CDN like Amazon S3. It's infinitely superior in performance and scalability while costing a fraction of the price. It's not universally better than the traditional rent-a-server option, but for static content websites it really does make sense.
A typical Jamstack website will be made out of multiple template files that are put together by a static site generator. It may need to process thousands of these files to generate a final result which is then uploaded somewhere to be served at scale. Since this is an emerging technology, there are tens of website generators out there: Next.js, Gatsby, Hexo seem to be the most known, but there are many more.

Most of the popular generators are written in Javascript, but there are a few notable exceptions like Hugo (Go) and Jekyll (Ruby).

Implementing this in Elixir was an opportunity for me to get some experience with parts of the language I'm not really familiar with: file-handling and I/O, making binary files with escript and using template processors. The fact that it's trivial to create a process for each file made me think Elixir would be a fun language to tackle this in, so I gave it a shot.

The starting point

11ty is one of the existing static site generators and it has been making rounds on Twitter for being straightforward and providing a great developer experience, so I used that as a starting point. My goal was to try to make a CLI tool that would try to do what 11ty does, and run both tools in the same configuration to understand the nuances and performance differences.

I could have picked any other generator, but the documentation for 11ty, along with video tutorials for building simple websites made me feel that it was a great starting point.

Template Processors

When I was looking into implementing this, I thought the processing of template languages like Pug, Liquid, Markdown and Haml would be an issue and that I would have to write processors for each template, but each of those would be a project on their own. After some searching I was really glad to see that there are Elixir libraries to process them. This puts me in an ideal situation, because I don't need to get caught in the details of processing the templates, I just need to write some logic to look for files and process them.

Proof of Concept

I have made the result of this toy project available on GitHub. There's definitely potential, but there's also some bugs. I worked on this while my newborn napped for the past week and while I might not have more time to work on it, I also didn't want what I did to go to waste, so it's out there. If you want to contribute, feel free to add a pull request submitting a new feature or fixing an issue, that would be most welcome.

Final Thoughts

I did end up succeeding in generating a CLI tool that parses HTML, Pug and Markdown templates, but I don't like the process of cloning and compiling the project to be able to use it. I recently heard that you can install some of these tools with mix archive.install , so that would be cool to explore next. Seeing as CloudFlare has made their developer docs available as some 1,600 content heavy markdown pages, this would be the ultimate performance benchmark :)

In actually trying to do this I ended up learning a lot about implementation details I would have never imagined had I just tried to guess how these tools work. There is a lot that can be done with EEx and HEEx in particular in order to build cool static websites but I've moved on to something else for the near future. (diapers, mostly 😂)