Reboot the site

It’s been a full 8 years and change since I wrote my last post. I have been busy work wise and in private life, and I desperately wanted to change the site architecturally. I wanted a new static site generator since the old one (BlazeBlogger) was lacking in a great number of ways.

Basically I have been putting off redoing the site because I felt that writing a static site generator would be a fun project. And it would. But honestly that project will not happen the next many years for me I think and I really have things I want to write about.

Therefore, the site now renders with Hugo using one of the most standard themes available. It is not everything that I want, in many ways it is much more than I want, but it works. I picked the better posts from the old site and converted them, the intention is to move this site forward from here.

I have a couple of points to make on the concept of site generation, so let me get them off of my shoulders below.

Static site generation

Static site generation is amazing; having less logic running server side in order for someone to view a page is universally good.

• It’s good for performance, because your server will serve static content and no operation can be faster than that
• It’s good for scalability, as you can add more servers and they can all individually serve static content without the need for coordination
• It’s good for security, as a simpler backend server has less logic and therefore less logic to be compromised. In the event server software is found to be lacking beyond repair, serving static files is such a common task that one can trivially change from one stack to another (there is a myriad of HTTP servers for local hosting and even more vendors offering simple HTTP hosting of static files, from the hyper-scalers to the local outfits)
• It’s good for reliability. Complex systems break in complex ways - simple static file serving is a relatively simple problem, one where troubleshooting is approachable

This does not mean the pages have to be static in their behaviour; you can execute any amount of code on the client side (JavaScript running in the browser of the end user) - much functionality can run like this (but obviously security functions would generally not be able to run client side).

Hugo maturity

Hugo is still in early enough stages of development that theme/engine compatibility due to frequent incompatible changes is an issue. That sucks - but I found a release of a theme that will work with the current version of hugo available in Debian Trixie which is where I’m at desktop wise at this moment.

It turns out that when using Hugo v0.131, the current master branch of the “ananke” theme which is what is suggested in the Hugo quickstart guide, does not work. However, using the release/v2.12 branch of ananke will give you a theme that works flawlessly with the slightly dated Hugo version (as described here).

This is more a mindset thing perhaps. I really don’t want incompatible changes in software that I use. Sure new features are nice but not at the cost of having to re-work the existing body of work that I have produced through the years (decades). Of course a project in its early stages will undergo such changes - but for it to be long term useful it needs to stop that. Time will show if Hugo manages.

Documentation

Hugo itself appears to have excellent documentation. The themes, well, they appear to be side projects not integrated with Hugo proper. And that’s fine, but it means that as a newcomer to the platform you are recommended to use a theme, but left with no clues as to how to progress with building your site on that theme. Themes probably vary in quality of documentation, I am only referring to the (otherwise nice) ananke theme which the Hugo quickstart guide recommends.

Probably this is not as bad as I’m making it out to be - there is a learning curve and as a user you need to climb that. Google is a fantastic tool and there is a lot of information out there when you start learning how to find it.

The use of markdown

I know that pages can be written in more formats than Markdown, but realistically this does seem like the go-to. The format to use to have the most chance of using “whatever everyone else is”.

Now, Markdown is for the most part a useless format for document creation - let me explain why I believe that:

When building up a document (or site or other larger body of text in any form) you are going to want to apply some form of consistency in how you present the reader with information. I have some simple examples here that Markdown address very well:

• Paragraphs. I can write text as I would in my editor, breaking my lines with single line breaks for my own readability and putting a blank line in between paragraphs. This ultimately results in nicely readable paragraphs in the browser. No special codes needed, a very natural experience. This is the same approach as LaTeX uses and it works very well indeed.
• Bold, italics. By decorating a word with asterisks or underscores, one can produce bold or slanted text. This works fairly well assuming that the asterisk is not something you need to use very much in the text you are writing - which is probably a fair assumption.

However, look at any book or any web site with some amount of content. It’s not just paragraphs and bold text. You will see things like information boxes, code blocks, hints and tips, pictures and so forth. Let’s call them idiomatic constructs. The problem is that the possible set of idiomatic constructs is practically infinite - it is up to the imagination of the author what will be used in whatever is being written.

Markdown is not an extensible language. Markdown has a small number of built-in features that it supports very well, but as an author you are left with no options for building up your own idiomatic construct, your own “function” or “module” for efficient re-use throughout your document.

This shows. As soon as you go past the built in features, suddenly you are no longer writing markdown. You start writing escaped sequences of other languages (e.g. XML) to escape the confines of Markdown and reach the formatting engine (Hugo in this case) with the more advanced constructs.

So while I can write this text as easy as:

So while I can write *this text* as easy as:

Referring to size_t requires:

Referring to {{<hl "c++">}}size_t{{</hl>}} requires:

The contrast is stark. This is a fundamental problem of having a primitive markup language with no extensibility, and then employing that format for a use that is far out of its league. Again, not a Hugo problem as such, not a Markdown problem either as such (if Markdown was only ever used for grocery lists), but a problem of choosing unsuitable languages (Markdown) for the task (documents more complex than grocery lists or GitHub readme files).

In conclusion

I’m not hating on Hugo or even Markdown - I got the site up and running and I am grateful for the work that was put into Hugo and the Ananke theme to make this possible.

There’s some learning to do. There’s a lot of rough edges on the site. But it’s a start, and it’s here now - unlike some hypothetical site generator I could create one day in the future. This is the art of compromise, which is something we all have to practice. That doesn’t mean I can’t point out when a format is a poor fit for purpose - but know that doing so I also know full well that I chose to adopt the technology. There’s no blame intended here - there may be a bit of harsh love, but no blame.