New year, new website. Yay :) For two or three years, I used About.me for a web presentation and Medium.com for writing. No more.
I tried many platforms over the years — Blogspot, Wordpress, Ghost… but nothing really stuck until Medium. However, I’ve become rather disenchanted with Medium policies at this point. As many other people. I’m not against subscription models, but Medium has been pursuing monetization way more aggressively than I’m comfortable with. I dislike how we keep losing control of our data even further.
That said, I’m quite bad at writing regularly. I usually end up with a bunch of drafts all over the place. We shall see how it will go this time; I’ve got some tricks up my sleeve to make and finish content often.
Anyway, so I took this as an opportunity to learn something "new" (and refresh my front-end skills). I had a few ideas about how my new site should work:
-
writing posts in AsciiDoc
-
extremely fast, accessible, and responsive (duh)
-
that implies (almost) no Javascript, low-complexity CSS frameworks, and no Web fonts
-
as much managed as possible with zero maintenance on my side
-
yet ideally for free :)
This led me in the direction of static generators and plain static hosting.
AsciiDoc
You might ask — why AsciiDoc? AsciiDoc is everything Markdown wants to be. It has non-ambiguous specification, i.e. no flavors (thank godness). You can make a lot of complex content with it such as table of contents, cross references, footnotes. It has a quite refined support of tables. Github supports it natively… I mean why are you still using MarkDown? :)
Hugo
I played with Gatsby in the past, but it’s rather too much Javascript for my needs this time. And too much React for that matter. Then I discovered Hugo and found out it supports Asciidoc out of box. So I had to try it.
Hugo claims to be "the world’s fastest framework for building websites." I might even believe it, it’s blazingly fast. No wonder since it’s written in Go. It seems to scale well even when you go into thousands of pages according to the random benchmarks around the internet. This is not my case, it’s just nice to know it might be useful in some other projects. It offers tons of features with a lot of flexibility; you get things like taxonomies or syntax highlighting out of box.
I planned to use one of the existing themes, but in the end I decided to write one from scratch. It was a good exercise to understand the innards of Hugo better. And not that difficult one. Hugo uses Go’s templating libraries which is enough easy to learn. You create a few template files for specific content Hugo blocks like single page or list and that’s it. Hugo also has an asset processing which I use to minify and fingerprint site custom CSS style and SVGs.
If you wonder how such a template looks like, here’s an example from official Hugo documentation:
{{ define "main" }}
<main>
<article>
<header>
<h1>{{.Title}}</h1>
</header>
<!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
{{.Content}}
</article>
<ul>
<!-- Ranges through content/posts/*.md -->
{{ range .Pages }}
<li>
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
</li>
{{ end }}
</ul>
</main>
{{ end }}Design
Let’s face it, there is no research behind this :D I designed it how I wish the other blogs or personal websites were designed like. Minimalistic and clean with important information in logical places. I don’t say I did it right, but that was the intent. I’ll keep improving it over the time; the mobile version still needs a bit more love. Let’s call this design an MVP. :)
CSS framework
The biggest trouble I had was what CSS framework I should pick. I wanted only grids, ideally in flexbox, and basic typography. I checked out Miligram, Picnic, Spectre, and ended up with good old PureCSS. I discovered MiniCSS later on, which I’ll definitely try next time.
PureCSS has flexbox-based responsive grids and small footprint.
The combination of base and grids delivered by jsDelivr clocks at 3.2KB which is okay.
The only thing I quite dislike is PureCSS predefines font-family and font-size for grids,
which means you need to explicitly override it. Otherwise it’s the usual.
Other tools
I generated the color scheme with Coolors, although I had to tune the colors manually — they didn’t pass some of the accessibility contrast tests. The avatar was created with avataaars generator.
Hosting
Again I tried to Keep It Simple Stupid. Github Pages looked like a reasonable option as I pay for a Github account. They support custom domains with HTTPs and it’s really a low hassle solution. I wish they offered an access log though.
I’ve got a private repo zdenekfarana.com with Hugo sources.
Hugo builds the website into docs folder which Github uses as a source for the Pages.
Then it’s just the question of pointing a DNS record to the right location and you’re set.
I don’t really need a continuous build, I simply run hugo command and commit & push.
Voi-là, the website gets updated.
Analytics
Well, there are no analytics right now. I wish I had that access log, that would be good enough for me. I don’t want to use Google Analytics, so I looked around for alternatives. I’ve found some interesting ones, but in the end I decided to skip it and add it later. It’s gonna be a topic for one of the next articles.
Lighthouse audit
If you’re not familiar with Lighthouse, it’s a tool for improving the quality of web sites. You can find it in Audit tab of Chrome Dev Tools. It helped me with identifying some minor issues which were easy to fix. I gotta say it can be pretty useful, so don’t be afraid to use it. My final results ain’t bad:
Summary
I’ve enjoyed this exercise very much. I’d say it was a breeze working with Hugo. Mostly it was joy, there were only minor frustrations. Sadly, I’ve also finished a bottle of 30 years old Tawny I brought back from my last year’s trip to Portugal. Anyway, I guess I should port the content from Medium!