This project was primarily motivated my annoyance with the long and arduous process of manually editing the html files that make up the pages of this website and on the premise that by reducing the friction of composing posts for this site, I would be more likely to contribute to it more often. The obvious solution to these problems was to streamline the post creation process by writing a static site generator. Certainly not a novel idea and ground that has been tread many times before with more fully featured and robust solutions than what I had in mind. Nevertheless, I thought it would be kind of fun, and a good way to occupy myself while the world remained sheltered in place. This project was originally conceived in the early days of the covid-19 pandemic, and I worked on it sporadically over the course of a few months

With a new project to work on, of course it was a perfect time to try out a new language. I decided on Rust, the much hyped performance and safety oriented systems language. Of course there was nothing about this project that really required the level of performance that Rust affords, but I thought it would be a good opportunity to challenge myself and learn some things all the same. I say challenge myself because Rust is certainly a lower level language than what I write in day to day

Overview

In keeping with the simple nature of the site, I wanted to make the process of generating it as simple as possible. Since most pages in the site follow the same general structure with regards the way that content is stored and displayed, I thought that using a markdown like syntax for the input files would suite my needs well. Markdown is easily readable by humans in its raw form and more importantly, relatively easy to write. My general idea for how I wanted the generator to work is as follows: given a directory of markdown files, the posts generate a html file for each of the markdown files and place it in an output directory along with all the required assets and static content.

As of now, the markdown parser that I've built just understands a limited subset of the general markdown syntax but is still able to output pages with acceptable structure and styling. The input files contain what I call markdown lite and they support a handful of text and image formatting styles. text, subheadings, images, codeblocks, and inline code at time of writing

Challenges

Almost all the problems I encountered in the process of writing this program stemmed from my choice of Rust. Since this was my first project using the language I ran into all off the stumbling blocks that most people do when trying the language out for the first time. The infamous borrow checker and lifetimes took me a while to wrap my head around so progress was quite slow for the first month or so I worked on it. Over time however, I gradually got used to thinking about ownership consistently and started getting less and less compile time errors. Using Rust for this project definitely forced me to think a bit differently about how I was designing the program and while it was frustrating in the beginning, I really was enjoying writing it by the midpoint of the project. I can see why there are so many Rust evangelists out there quick to extol the language's benefits and features

Most of the non language specific challenges for the project were centered around attempts to keep the simplicity of the project intact. Things like embedding the post metadata in a hidden header of each markdown file allowed me to keep all the information about each page contained within a single file, something that I'm happy about. This metadata is used extensively, from naming the outputted file, to populating the tags of each post, and even determining the ordering of the posts on the index and archive pages. Except for those aforementioned pages, all the pages within the site are dynamically generated based on the inputted markdown files.

Result

Now I have a serviceable static site generator and some experience with Rust so those are two big wins. Admittedly, having this site generator has not increased my output on this site at all as evidenced by the two-month gap between finishing it and writing this post, so my theory about reducing friction was not the only cause of my abysmal writing output. Even so, I'm relatively happy accomplishing 12 of my goals for this project.

Project Resources

I've published the code used for this project on Github here.