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
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
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.
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.
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
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, …).
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.
- Initial release
i had even set-up automatic back-ups and upgrades for Wordpress (predominantly for security fixes) but they broke at some point. ↩︎
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. ↩︎
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. ↩︎
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. ↩︎
there have been multiple Hugo version bumps between starting and finishing this website… ↩︎
usually the last 20% of work takes 50% of the time. where 100% is practically speaking never achieved (logarithmic curve). For many use-cases 80% is more than sufficient. Not to be confused with the Pareto principle or 80/20 rule. ↩︎
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. ↩︎
might also have been a settings issue on my end but out of the box none worked for HTML nor SCSS with Hugo syntax. ↩︎
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. ↩︎
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
darkenfunctions for colors) ↩︎
lines of code. ↩︎
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. ↩︎
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. ↩︎