Sunday 20 January 2019 — TECH
As you might notice, this web site has a new theme, even if it is similar to the one it had before. Why?
I hit a problem with the first post of 2019. The post would not appear when I built the site. I looked at it but could not see anything wrong. I tried changing the year in the post back to 2018 and it appeared. I assumed that there was something wrong in the template code running the site which meant it would only work up to the end of 2018. I started to look for the bug and quickly realised that it would take a very long time to find it. The code in the theme I was using worked, and looked to be well written, but it was not well notated or documented so it was very hard to guess what different sections did, or even to find out which file did what in generating the pages. The previous theme had been adapted from an earlier theme, which itself was adapted from an earlier. There was lots of evidence of this, with code still in place which had not been udpated to reflect the names of later themes and section sof code which were still there, but no longer used. In short, it was classic hacking: using coding knowledge to adapt something, without ever really understanding the structure of the code, its data structures and functions. Hacking can be good, in that it makes something happen fast and cheap, but when you hit a problem or want to develop further, the layers of hacked code add difficulties. You are studying layers of complexity built on top of what mayhave been muddled code in the first place.
I took the decision that I should write my own theme for the site from scratch, understanding what the code did, doing only what it needed to do, and beng careful to give things sensible names and annnotate fully. I wanted to keep the main visual and functional design features of the site, but behind the scenes I would have something I fully understood, and not something I kept hacking, on top of at least two others people’ hacks!
About ten minutes after I made that decision, I saw the error in the post that would not appear. I had month and date numbers the wrong way round! It was blindingly obvious: the date did not make sense, so the post had an error so it could not be processed. It should not have worked with the year set to 2018 either, but it did. I decided to press on with the project to write my own Hugo theme, from first principles.
I created a copy of this site and an empty theme. I read the Hugo deocumentation about templates and several tutorials about making a theme. Although the language for coding Hugo templates is Google’s “Go”, which I don’t know, most of the template contents are html and css, which I do. I didn’t think it would be necessary to learn the whole of Go to create a template.
It took me many hours to even get a list of posts on the home page working, or to get a single post to appear, even without any styling. The breakthrough was a throw-away line in part of the Hugo documentation about “troubleshooting themes”, which said something like “beginners often make this mistake…” which was about passing a context to another piece of code (so that the code can access the data it has to work on). It was a classic piece of IT learning, where something fundamental about the operation of a system and the language used to express it is taken completely for granted (and so not mentioned or explained) by those who know, and is utterly baffling to those who don’t. It didn’t help that the code for passing a context is adding a single period (“.”) after the name of the code you are calling. Once that was realised, I fairly quickly had posts listing, pages displaying and even pagination (limiting the number of posts on a list page and having links to more pages of posts as required) working. I was finally onto crafting html and css to display those lists and posts as I wanted and then it was into the details of design and polish in what was already a working site.
I took the opportunity to simplify. The site no longer uses tags, only a limited number of categories. I know how to make tags work, but decided that they don’t really fit the content here. I reduced the number of css classes to approximately a quarter of what there had been before and consciously tried to make it very obvious what every piece of code and class was for.
In the spirit of Open Source Software, I will share what I have made, but I will wait to fix the inevitable bugs, and document it thoroughly, before I do.
The Hugo system (which generates a web site from markdown files and templates) is extremely fast and remarkably powerful. I am amazed at what you can potentially do with it to make secure, fast and effective web sites. It is not always helpful: for example, it should simply have told me that the date in the 2019 post was incorrect instead of parsing it into something that could not be placed in the list of dates. It’s not really something you could give someone who has no technical background and just wants to write. It keeps techies in a (usually unpaid) job, I suppose.
I liked using Wordpress, which hides away the code and allows you to create blogposts and pages in what looks and feels like a word processor. The cost of that, though, is quite a heavy load on the web server and an infrastructure where very few users understand how it works and what, in detail, is going on. That, in turn, creates an opportunity for hackers to break in, steal and damage and every patch to keep them out, makes things even more complex.
I’d like to see a desktop based front-end for Hugo, where you can edit fields to poduce content and it produces the markdown files in the right format and then processes them to produce and upload the web site. There are server based systems that do this already, but I feel a desktop version might be simpler and more secure, as well as allowing you to host your site wherever you want. If I ever have time, I might work on that myself.