Release notes

The publishing mechanism used to produce this website is a topic perhaps of least interest to a structural engineer, nonetheless, I’d like to, if only to keep a note of the work done and changes made. But first some trivia.

By 2010, I was fed-up with a popular open source web publishing software I’d been using since 2004. Its code base was changing so rapidly that I could not keep up. To quote Tom Preston-Werner, Blogging Like a Hacker (2008):

I already knew a lot about what I didn’t want. I was tired of complicated blogging engines like WordPress and Mephisto. I wanted to write great posts, not style a zillion template pages, moderate comments all day long, and constantly lag behind the latest software release.

On Sunday, October 19th, I sat down in my San Francisco apartment with a glass of apple cider and a clear mind. After a period of reflection, I had an idea. While I’m not specifically trained as an author of prose, I am trained as an author of code. What would happen if I approached blogging from a software development perspective? What would that look like?

By 2011, fatigued by bloat and potential vulnerabilities of open source web publishing software stack, Tom’s post was a raging fire among developers and wannabes. It kick-started static site generator revolution, and helped people realise that writing one was not some dark art that needed an army of engineers and volunteers for it to be useful.1 One could also get rid of all the complexities of running and managing database instances, and keep them from corrupting over time, be it from upgrades or from encoding.

These trends helped re-assess my needs too. For instance, questioning the need to use traditional web service hosts, or the need for pre-requisites like LAMP stack to be able to host simple websites. Having such software in the cloud and shared across users amplified attack vectors for hapless publishers.2 And for what really? For the comfort of publishing on the road by accessing an archaic login system without multi-factor authentication? It’s ridiculous in hindsight of course, but there was a time many of us thought that there really was no alternative.

In 2012, after years of grappling with software bloat, security gaffes, and latency of various web publishing services, I decided to take control of my publishing set-up. My objectives in maintaining control over publishing work-flow were:

  1. To write and present code, math, and prose effortlessly
  2. Enable login-less and cryptographically-secure publishing
  3. Ensure portability of notes together with track changes
  4. Maintain bare bones, readable, safe, and low-dependency code base
  5. Use a decent template engine to be able to do more with less code

After some searching and evaluating, I found Chisel — a simple python script to turn notes, written in markdown, into html pages, and auto-arrange them in a neatly linked structure. It employed Jinja, a minimalist, performant template engine; git for tracking changes in both notes and code; and GitHub for static site hosting. I subsequently added a few features to Chisel I wanted for myself.

Both the model and the controller are local processes, having decided long ago that I would run nothing in the cloud. Only the view produced (from a combination of model and controller processes) is pushed to the host via git.3 Today I am able to say that after nine years of sustained use of this above set-up, it remains very usable. The code base has remained the same, with lines of code never exceeding more than a few overall, and it is as readable today as I had first found it. The only noteworthy maintenance I undertook was in 2019-20, when concerned by the need to phase out python2 code, I sat down to re-factor Chisel to run on python3. I did so without discernible change in code.

This is a set of release notes, covering features or updates, from that exercise done a year ago, and split into model-view-controller process categories.

Controller

  1. Blurb feature for each note (new)
  2. Date is ISO 8601 compliant (new)
  3. Fenced code markdown extension enabled (new)
  4. Generator specific config file (new)
  5. Re-factored to python 3 (new)
  6. Select contributions sent upstream via pull requests (update)

Model

  1. Feed templates now in Atom format; RSS format superseded (new)
  2. Keyboard-only navigation with circular return back to homepage (update)
  3. Maintain note count continuity from homepage to archive (new)
  4. Notes split between homepage and archive page sans duplication (new)
  5. Template parameters: single config file, selective imports (new)
  6. Templates modularised with child templates (new)

View

  1. Custom font calls eliminated (update)
  2. Dark mode honouring user-set appearance settings on devices (update)
  3. Numerous template snippets re-factored to be modular (update)
  4. Re-design, html5 and css3 compliant (new)
  5. Render math with KaTeX engine (new)
  6. Snippets re-formatted using black for improved readability (new)

  1. This was especially true for medium to low volume publishers, who were not producing 1,000+ posts a month, and who did not need to own, maintain, upgrade this web application stack on a server, stay subscribed to application security news, and patch at a moment’s notice upon discovering vulnerabilities. 

  2. I endured two security breaches between 2002–6, which were scary, and I realised that if I were to continue with this hobby (of writing on the web), then I could not afford to remain oblivious to the workings of web hosts or software they offered access to. 

  3. This eliminates the need for a feature-rich web server on the host, and is therefore ideal for hosting a locally generated static site.