Published: 26 Aug 2024
Last updated: 7 Sep 2024
Approximately 18 months after putting together a new SvelteKit website, I’ve put together another one to replace it, functionally doing the same thing - so why the change? It was to serve two directions, scratch my technological itch whilst an excuse to have somewhere to put my writings. Over the intervening months I’ve deliberately tilted towards just the writing side - the scratch to improve my weakness of writing and to simply get better (or as I often frame it, “less worse”) at thoughts into words, sentences and paragraphs. The SvelteKit website still needed work I didn’t want to do, and I knew trying to stand still in JS-land would end in pain at some point in the near future. Whether or not this jump to Hugo is permanent, I don’t know, but the concept of Static Site Generators look a lot closer to I what I want - static html pages generated via Markdown, with a little intelligence to generate all my blogs in a list, RSS etc. etc.
Over the course of making this website, I’d like to also link some useful resources and give some of my own tips I’ve put together whilst building it. It didn’t take me much time to put something together, and for that I can only thank the kindness of shared knowledge from strangers.
Getting the initial blog together
Hugo’s quick start guide does certainly get you started quickly, but its very surface level and doesn’t dive into a lot. The documentation is also pretty good from initial experience, but there’s an initial small learning curve (especially if you jump in without any knowledge of Golang, which is what Hugo’s written in) and sometimes its useful to look at a fully-built example and tinker around the edges.
These two links were the most useful for me - this blog is 90+% stolen from Mogwai’s design with a few tweaks here and there - but both proved to be very valuable in putting the initial building blocks of how a typical blog written in Hugo works.
Since Hugo is still yet to have a 1.0 release, blog posts are often out-of-date, if only for a few minor things. Here’s a few assorted tips for any readers to avoid figuring out yourselves:
hugo.toml(the config file), is often referred to its old nameconfig.toml.- Both guides use the yaml format for the ‘front-matter’ used in the
.mdfiles for blog posts, when in fact Hugo supports both toml and json as well. (For what its worth, Hugo supports all three formats for its config file - but it seems obviously sensible to use just one configuration markup language? Maybe that’s just me /shrug) - I could not get
{{- range where site.RegularPages "Type" "in" site.Params.mainSections }}to work from Mogwai’s guide (see “Step 5c - blog post list layout). I replaced this in mylayouts/blog/list.htmlwith{ range .Pages.ByPublishDate.Reverse }(from zwbetz’s list Page Layout).
There were also a few other miscellaneous additions I made.
RSS
Conveniently, the same blog I found getting this up-to-speed also provided a quick addendum to getting RSS up-and-running. Although this also took a bit of work correctly. Since I have multiple “categories” set up (rather than just a Blog section and static pages otherwise), I couldn’t extend the {{ range where .Site.RegularPages "Section" "blog" }} to also loop over my other non-blog categories. I didn’t want to leave the {{ range $pages }} that the default template Hugo comes with either, as it included all the static pages in the RSS feed, such as the home page.
To solve this, I instead went used a front-matter parameter exclusively for the RSS to ignore. So to exclude the home page, the front-matter would have a rss_ignore = true flag, and update the RSS range to {{- range (where .Site.Pages "Params.rss_ignore" "ne" "false") }} - only including pages without the rss_ignore = true parameter as it would equal true if not explicitly set otherwise.
There’s also some extra configuration in the hugo.toml that Hugo can use for filling out the .xml file, as well as a feed reference in the head element of the pages.
“Last Modified Date”
In my old blog, I had included the concept of a “last updated” tag but it was all manually controlled, and unsurprisingly I’d often forget. A quick Google found that Hugo can handle that itself, and use git to source the dates instead. Surprisingly simple to get working.
Edit: Turns out that due to Cloudflare doing a shallow “clone”, then by default the “Last modified” date will automatically default to the latest build date. By adding git fetch --unshallow to the build command, this resolves that issue. See Bryce Wray’s “Get good Git info from Hugo” blog which addresses this issue.
robots.txt
Hugo comes with a free robots.txt template that’s dead simple to enable. So simple that I’ve barely seen a mention of it when building a blog from scratch - but if you’re deploying and want it to be actually indexed by google? Still important.
Commenting system (Cusdis)
I was looking for a commenting system to integrate within my website, and while Hugo supports Disqus out of the box with its own internal template - I preferred to use something open-source (and have heard some rather negative things about Disqus over the years), and found Cusdis offered as an alternative, and even provided an SDK to make it ultra easy to integrate within the website. In my partial single.html, all I need to do is copy the following:
<div id="cusdis_thread"
data-host="https://cusdis.com"
data-app-id="d094df31-7f65-4d28-a74c-e01db98fdb81"
data-page-id="{{ .RelPermalink }}"
data-page-url="{{ .RelPermalink }}"
data-page-title="{{ .Title }}"
data-theme="dark"
></div>
<script async defer src="https://cusdis.com/js/cusdis.es.js"></script>
at the bottom of the html page.
Simply creating an account with Cusdis, logging into the dashboard, and clicking the “Embeded code” button (their misspelling, not mine!) will get the right data-app-id for your own account.
My first impressions of Hugo
I’ve been very impressed with Hugo after getting over the small learning curve of its Go syntax with templating - and despite the many other features it offers I can use it in a rather simple and brainless way, stitching together html fragments (or “partials” in Hugo lingo) with a few simple loops to handle the lists and navbar buttons - Hugo does most of the work for me. My only potential concern is that by being under active development, and beta development at that (no v1.0 in sight as far as I can see publicly for Hugo) that things will break badly - which is why I’ve tried to make this website as simple as possible, and I’ll take upgrading one single binary periodically over the uber-fractured package-fest that is JavaScript and npm.
Initial future of the website
The future of this website over the next few days is going to be wholesale moving my writings over from my old website to here, nothing if time-consuming, with only a few tweaks here as the format is largely the same. Those should be appearing in the next few days/weeks/months, and I’ll have a small mark denoting when they were ‘initially’ written. Other than that (and spamming up the RSS feed), I’m planning to both get back to my regular writing schedule, with the extra focus on trying to get a blog post out every few weeks discussing whatever comes to mind. That was the one thing that was rather neglected in the last iteration due a lack of an obvious theme - my hope is making the ploy of saying “I will do this” into the void, pretending lots are reading this will be enough of a placebo effect to get that part of the engine going.
Let’s hope, for my sake, that I’m not here in another 18 months time going through the same rig-ma-role proclaiming that “this is my last move, I swear” - I know from experience programmers love going for needless perfection and indulging in pointless diversions, it comes with the territory :)
