Rethinking my Webpage Generation

Published: 04/01/2020

Every time I do anything I keep going up levels of abstraction until instead of accomplishing whatever I set out to do I'm stuck pondering what is it that I'm going to do with my life anyway. This time I stopped one level short and refactored my website. Hopefully everything looks exactly the same to you! It only took a couple hours to achieve that. Since my original problem was wanting to write a blog post I'll now circle back to that problem by writing about the myriad changes which are (hopefully) invisible to you. I'm not sure if this is one level up or down in interest to the average person from me describing a dream I had or a notable bowel movement. These are the perils of starting a blog when you have nothing to say.

Basically the problem my refactor was solving goes like this: In the beginning I had a blog post. Blog 0. Then there was a second blog post. Of course around every blog post is some html that I want to be mostly the same across blogs. Menus to go forward and backwards. Headers to get my beautiful css. When you just have two to three blogs or you're confident you'll never want to change the layout, copy and paste are a satisfactory solution. But since I keep churning out garbage and the layout is also garbage a more long term solution is required.

At this point the astute reader will cry out "have you heard of wordpress? or substack? or github pages?". Once upon a time I published on Google Blogger. Somehow I can't trust centralized services though. Google Blogger hasn't been Google+ed yet (or Google Readered or Google Waved or ...) but it does have the air of the passe. Do I really want to publish on Google Blogger in 2020? And maybe today Medium is hip and cool and easy. But do I trust it be those things in 2025? I guess it's just like my about me says. I'd rather be uniquely bad.

At this point the astuter reader may cry out "have you heard of angular? Or [my preferred front end stack]? Just because you're crafting your own bespoke website doesn't mean you have to figure out how to minimize html duplication!". To which I reply: yes, but I cannot read. I'll never forget at an AI Safety Workshop when one of the organizers declared that they could not read. And ever since then I've realized that I can't really read either. I can't just pore over some documentation and know how to make a website. I think what I've done here constitutes a buggy and partial reimplementation of Angular. But goddamn it its my buggy and partial reimplementation and I know how to use it.

Design Doc

As I redesigned I realized my vision was just slightly too big to fit in my head so I wrote out a design document of sorts to track the big picture. This a touched up version of what I wrote for myself:

The central abstraction this redesign created is separating my webpages into three parts: content, template and data.

The content is stuff that's truly unique to a given webpage. Except not because after refactoring I added a podcast menu item and duplicated the content of my two podcasts since I didn't want to break the original links. In the case of this webpage the content is the blog post itself.

The template is the duplicated html structure which is important to have around a blog. Right now I have two templates: blog.temp (which should be called periodical.temp since its the template for blogs and podcasts) and toplevel.temp which is the template for my blog and podcast indexes, the aboutme page and my experiments page.

The data is what ties it all together. Each webpage has an associated json file which are organized in a data/ folder with the same directory structure as they have on the final website. The data file has any information that will be needed to create the website such as:

I designed a nice syntax for the template files to fill in the data and content. I have a python script which goes through the template files and replaces the following tags with the appropriate information. The tags are as follows:

Things I Learned

Whenever I write even the simplest code I end up googling a dozen different things most of which I can't help but think I knew at one point. Here is a list of things I learned while doing this refactor. I've written it out for the twin purposes that maybe something in the list will be useful to you and maybe by writing these things out I'll actually remember them and not need to google them in the future. In the past I've always had a dismissive attitude towards memorization. What value could there be in actually knowing things when I can just outsource all my knowledge collection and storage to digital systems I don't control? But I'm starting to think all the time spent Googling adds up and there's value in having knowledge conveniently stored in the shape of your synapses.