Rewriting My Static Site Generator

Written By: Jake Bauer | Posted: 2020-05-22 | Last Updated: 2020-05-24

After a brief, two day hiatus in posting to refill my creative juices, I’m back with a rewrite of the script I use to generate my website. This has been a long time coming (for me, anyways) as my old script had become too messy to work with and I wanted to switch to using pandoc to compile my webpages. Back when I originally wrote the script, I was still fairly new to shell scripting and the quality of the code reflects that. This new script is much easier to read, much better laid out, and is far easier to extend and adapt in the future. It’s also now possible to use this script for sites other than my own, as long as those sites have their markdown files structured the same way.

Previously, I was using markdown as the program to take my .md files and transform them into .html files. Unfortunately, it had a couple of issues: It wouldn’t interpret triple-backticks as code blocks so I had to use <pre><code> anywhere I wanted a code block, and it would add empty <p> tags before and after <img> and <figure> tags. Additionally, using pandoc also enables me to add simple syntax highlighting for code blocks since it does syntax highlighting as part of the transformation process.

I also took the time to make sure that the syntax highlighting colour scheme I’m using has an appropriate set of contrast ratios. I targeted a minimum ratio of 4.5:1 and I ended up basing the colour scheme off of the iceberg colour scheme which I also use in Vim.

One other thing that I wanted to do with this rewrite was to make my script POSIX-compliant so it is as portable as possible. My script used to require bash but now it should work with any POSIX-compliant shell. It should also now only be using POSIX-compliant flags in POSIX programs.

Update: After further testing, I’ve switched from using tput to ANSI escape codes for colours, added the -e flag to the sed commands, and added a newline everytime I use the a or i command with sed. These changes were required to get the script to work on FreeBSD. As long as pandoc is available on a system, the script should now be portable between all *nix systems (I hope).

This new script clocks in at 7207 bytes, 235 total lines, and 180 source lines of code as of the time of writing. This is in comparison to the old script’s 10812 bytes, 253 total lines, and 152 source lines of code. This is mostly due to the fact that the new script is easier to read and therefore doesn’t require as many comments. Also, adding syntax highlighting only increased the size of my main CSS file by ~1kB.

I am considering releasing this script, along with documentation, examples, and my publish script (which also needs to be made POSIX-compliant), as a separate project which could be used by anyone looking for a simple static site generator. Before I do that, however, I would like to work on scripts to transform the HTML files output by the compilation script into Gemini- and Gopher-compatible syntax. I am thinking of writing perl scripts to accomplish this since parsing HTML is quite complicated and perl has a good set of libraries to accomplish that.

You can view the new script on SourceHut (mirror). If you really want to see the horrors of the old script, you’ll find it lurking in the commit history.

This is my twenty-sixth post for the #100DaysToOffload challenge. You can learn more about this challenge over at https://100daystooffload.com.