New website

New website

March 2020  2373  12 mins Website

Personal website #2316542575 is now online, after more than 10 years i have a personal website again. Last time my Wordpress install was so broken the hosting provider called me to have it fixed (affected other customers on the same instance). Since i did not want to spend any time on it, the reason it was neglected it in the first place, i took it offline and never looked back.

This time i wanted to keep things simple, a static website with handcrafted HTML + CSS. No more forced maintenance1, no security headaches, no frameworks that come and go, no dependencies to update, … a simple website that was trivial to maintain which i only have to update when i want to. After my HTML + CSS was done i had a dilemma: write my own (markdown-based) content generator or use an existing (static website) generator. Because i had no desire to jump in that problem space, i caved, and went for an existing static website generator. There are multiple generators available but i just went with the first that came up: Hugo (open source static website generator).
Since i’m not planning on forking or keeping an old version of Hugo around i will be forced to updated upon breaking changes. This fails my initial design goal of having no forced maintenance, if this proves to be a problem i will keep an old version around until i feel like upgrading2.

To learn Hugo i preferred to start from an existing theme (+ the official documentation) and mold it to my previously handcrafted HTML + CSS; this is a method that works very well for me. I got carried away though and started to slap together multiple existing themes into what you’re seeing now. Often only the UI was kept (or recreated) and code re-written3. Unfortunately due to the license of the resume theme i’m prohibited of open sourcing this theme. Since this is a personal site, and i never intended to create/maintain a Hugo theme itself, that was not a deal-breaker for me.
I also briefly looked into using an existing theme (there are many available for free) but found none that completely satisfied me and i already had my handcrafted HTML + CSS. In hindsight i should have picked the best one and call it a day, would have been far more efficient time wise. On the other hand now i’m back up-to-date with the front-end web world; a mixed bag.

Here is a quick overview of all themes this site is based on inspired by, for the resume i took the look and feel from hugo-devresume-theme (removed bootstrap and rewrote the css), the general layout is custom + based on hugo-book (heavily modified). Individual elements were taken from hugo-theme-meme, hugo-theme-learn and hugo-theme-dream.

For Javascript I’ve tried to keep it to a minimum (the goal was none, which failed) and the website can function perfectly without. The whole layout is CSS only. I got carried away though with features and even included third party libraries, at the time of writing: lazysizes, clipboardjs, lunr.js, glider, PhotoSwipe, KaTeX and mermaid. However all of them fulfil a specific function and can be easily disabled/removed/replaced if desired. I host their minified version so am not bothered with building them (this website does not use node.js nor npm). At the time of writing they are all still actively maintained. Besides those there are some small custom script snippets as well but all of the layout is done in CSS. I very much on purpose avoided any CSS or Javascript frameworks to avoid lock-in4.

In the end i’m quite pleased with the result although it took way more time than i care to admit5. It still could use more UI polish but i feel like i’m at the 80%6 mark which is sufficient.

Below are some thoughts on my experience with front-end development since my last experience was from more than a decade ago.

tl;dr It is not perfect but got the job done, has all the required features; would recommend (at the time of writing version 0.71).

The good

Hugo works pretty well and is quite feature complete. There are plenty of good themes available (free & open source) and it is popular enough you can google problems. For the issues i had there were workarounds available albeit not always pretty. Very customizable and most of the time not in the way.

It has “ok” documentation (lacks practical examples and information is sometimes spread out or incomplete; PR’s welcome i suppose) and is being actively developed. With the build in server the iteration cycle is very short for both development and content creation which saves you time.

The bad

Getting started, while most of it is straight forward once you get the gist of it i strongly advice to look at existing themes together with the documentation. The documentation it itself is only sufficient if you are already proficient with Hugo7. The content organization (your markdown files) was initially not that intuitive but is well documented.

As with all frameworks there are pitfalls. My latest annoyance was footnotes in shortcodes not working (those in the text you are reading now), nothing exotic and something you would expect to work out of the box. After spending a lot of time i found the answer. This is just an example.

It is not very extensible, if a feature is not supported you are out of luck. There is no plug-in system or custom code you can execute. This can be very annoying.

Nitpick: hugo is rather popular, and has been around for a while, it is a pity there is no proper Visual Studio (VS) Code plug-in available for formatting/linting Hugo specific syntax. None of the available extensions were able to do it8: Hugo Language and Syntax Support, hugofy nor Hugo Helper. This became so annoying i turned off code formatting all together and only (manually) ran the formatter on files which do not contain Hugo syntax. While strictly speaking this is more an VS Code problem than a Hugo problem, it is annoying never the less.

Webdevelopment through static site generators feels more like what Wordpress, Drupal or Joomla promised to be but never delivered for personal blogs. I’m a fan!

tl;dr CSS has come a long way and is significantly more powerful compared to 2 decades ago reducing the need for Javascript to do the layout. Unfortunately it is also still fragile from time to time and occasionally requires "black magic".

Lots, if not most, of time was wasted due to some unintuitive CSS behavior (it is all documented though) and the, occasionally, required black magic9 but i did manage to created the whole layout without Javascript; frustrations aside. So it does get the job done. I’ve used SCSS10 and feel like this is almost required for maintainability11.
The feature I’ve missed most is not being able to use the size of other elements in calc functions or using variables with hex color notation in the rgba function.

I will not go into much detail about HTML + CSS itself, one can already find plenty of opinions in blogposts/books about the subject. The combination of HTML + CSS generally worked quite well for me although CSS was a serious time sink in case issues arose and a major source of frustration when changes had undesired consequences (sometimes not detected right away).
The amount of CSS rules some websites use puzzled me, for example to show an embedded Vimeo video (through Hugo’s default shortcode) requires over 2000 CSS rules, i kid you not! Quite a surprise given the front-end world’s emphasis on reducing bandwidth e.g. by minifying assets like CSS. The whole core layout of this website is maybe 60 rules in total. One of the Hugo themes i have looked at uses Bootstrap (+10kLOC12 CSS), using an online analyzer it indicated over 84% of them were unused. Looking at the remaining code myself it could easily be simplified further; I rewrote it in <500LOC CSS keeping all functionality (mind you i’m a CSS novice and did not pay attention to line count what so ever).

While asset minification is common practice i would have expected full site static analysis minification tools to be common as well (further minimizing assets by e.g. reducing class name lengths). Maybe such tools exists already, or probably the problem is harder than i anticipate, but to me it seems like an obvious optimization that should be provided out of the box.

An aspect I’ve completely neglected for this site however is browser compatibility. It should work on the latest version of Chrome and Firefox and otherwise you’re on your own. I find it odd that the browser compatibility issue is a thing, the whole point of having a specification for HTML and CSS is preventing incompatibilities? It is 2020 this should have been a solved problem already; oh well life is not ideal i guess.

tl;dr good for what it is but i would never use it to write something serious in (full application, back-end, …).

To be fair its reputation precede itself, from never touch it (even not with a 10 foot pole) to write everything in Javascript (font-end, back-end and even embedded?!) the opinions vary a lot. I started biased towards the former point of view.

Having no notable prior experience with Javascript it was very easy to get into (being a professional programmer) and produce results, also the interoperability with the DOM is straight forward. Sure it has its quirks and i do prefer typed languages but to add simple features to a website (e.g. a back to top button) it works very well. Why you would ever want to write your back-end in Javascript is beyond me though13.
The dependency hell14 many libraries come with is mind blowing when coming from languages like C++. How can anybody maintain anything i wonder? That said i’ve noticed you can usually write your own version of what you need or find a good library with limited dependencies. I on purpose did not use npm for this website because i did not deem it worth additional complexity and effort. For a static website security concerns are neglectable so i don’t feel obligated to upgrade when the upstream library does. Even than minified distributables are available, so there is no need to compile it myself.

What surprised me was how few libraries were replaced by WebAssembly yet. For example Mermaid (draw diagrams) and lunr (local search) would be candidates for using WebAssembly from my point of view since they are non-trivial in neither complexity nor size. This would also allow to use another programming languages, if desired, since many languages support compiling to WebAssembly. That said i did not look into the WebAssembly specification and there might be good reasons why plain Javascript is still preferred or maybe it is simply still too early.

Changelog

2020-04-13

  • Initial release

  1. i had even set-up automatic back-ups and upgrades for Wordpress (predominantly for security fixes) but they broke at some point. ↩︎

  2. Hugo is written in Go, so as long as my system has support for the required Go version i should be fine. Go is executed on a VM so changes are i will be able to run the same executable for years in the future. ↩︎

  3. because as every developer knows it goes from “that can be done better”, “i will make this better” until finally “why do i spend a whole weekend on aligning elements for a feature i will likely not use”. Mistakes were made. ↩︎

  4. you become dependent on the framework and it requires more work if you decide to drop it or change framework. Some frameworks also have break changes after a while which force maintenance on your end even though you might not want to upgrade but a forced to e.g. due to bug fixes or specific new features. While this might be fine depending on your use-case i aimed to reduce maintenance as much as possible. ↩︎

  5. there have been multiple Hugo version bumps between starting and finishing this website… ↩︎

  6. usually the last 20% of work takes 50% of the time[citation needed]. where 100% is practically speaking never achieved (logarithmic curve)[citation needed]. For many use-cases 80% is more than sufficient. Not to be confused with the Pareto principle or 80/20 rule. ↩︎

  7. e.g. you look at the documentation and implement accordingly but, there it is staring at you. An error. You are mixing up two concepts but do not know it yet, the error is not helpful and the only way to debug is: google, trial and error or hope it clicks after reading through more documentation and stumble upon the concepts after which you make the connection. For people that already know these concepts the existing documentation will indeed be sufficient. ↩︎

  8. might also have been a settings issue on my end but out of the box none worked for HTML nor SCSS with Hugo syntax. ↩︎

  9. some behavior can only be achieved via a certain combination of settings which, for a beginner, are not intuitive and quite annoying e.g. is something wrong in my understanding or do i just need to look up the black magic combination. ↩︎

  10. unfortunately it is opinionated (e.g. request to make imports optional issue1, issue2, issue3, issue4) but still better than plain CSS. It does the job. ↩︎

  11. you really do not want to manually change constants everywhere and splitting up to files is useful as well outside of some other convenience functions it provides (like the lighten and darken functions for colors) ↩︎

  12. lines of code. ↩︎

  13. apart from terrible performance not being typed would be sufficient for me, yes i know TypeScript exists. I will not go in all the details, you can find plenty of books an opinions of people more informed about the subject than me. ↩︎

  14. dependency graphs seem to be large for even small libraries due to the overenthusiastic (?) and ease of using dependencies in libraries i presume. In my opinion every dependency should be carefully evaluated for cost/benefit (and eliminated if possible), but dependency management is a whole other subject on its own. ↩︎

Noticed an error in this post? Corrections are appreciated.
© Nelis Oostens