Hugo on Jayeless.net

Time for a Not-So-Fun Hugo Fact!

Thu, 12 May 2022 16:38:03 +1000

If you have a post with only one category, and choose between adding it to your post’s YAML metadata in one of the following ways:

categories:
- Category Name

categories: Category Name

Those are not the same! According to Hugo, the first one is an array (of one item), and the second one is a string. So then if you later want to make a template where you range all posts’ categories, it’s going to break because you can’t range a string, and the error message is not going to tell you which specific page is broken but only its category and what kind of feed is breaking (a section feed, a term feed, etc.), so you are going to have to go through every single one of your old posts in the relevant category until you find which one is causing the issue.

I mean sure, in retrospect it makes sense that Hugo wouldn’t know to interpret categories: Category Name as a single-item array and not a string. Indeed I guess I always knew there was something not-quite-right about that format, because I didn’t have that many old posts I had to fix up today. I had enough to be annoying, though. Mostly I don’t mind not having/using a CMS to manage my site but at times like this… 🤨

In other news, my RSS feeds include individual posts’ categories now, in line with a suggestion from this blog post about RSS Feed Best Practices . I actually have no idea which feed readers make use of this info (I don’t think mine does) but it seems potentially useful to some people so I added it. It does occur to me that it might also be useful to add section (e.g. Posts, Links, Book Reviews) if it means readers could filter sections they’re not interested in out of the full feed. I haven’t done that yet, though. I was traumatised enough by this damn array vs. string issue 🤣

EDIT: For SEO purposes, maybe I should actually add the error message you’ll see if you make the same mistake that I did. If you have categories listed in posts as strings, when you try to range them as arrays, your build will fail with errors that include range can't iterate over [CATEGORY NAME] like:

ERROR 2022/05/12 15:41:20 render of "term" failed: "/Users/jess/Documents/GitHub/jayeless.net/layouts/_default/rss.xml:75:13": execute of template failed: template: _default/rss.xml:75:13: executing "_default/rss.xml" at <$categories>: range can't iterate over Transport
ERROR 2022/05/12 15:41:20 render of "term" failed: "/Users/jess/Documents/GitHub/jayeless.net/layouts/_default/rss.xml:75:13": execute of template failed: template: _default/rss.xml:75:13: executing "_default/rss.xml" at <$categories>: range can't iterate over Transport
Error: Error building site: failed to render pages: render of "section" failed: "/Users/jess/Documents/GitHub/jayeless.net/layouts/_default/rss.xml:75:13": execute of template failed: template: _default/rss.xml:75:13: executing "_default/rss.xml" at <$categories>: range can't iterate over Food

Rambling on Hugo’s Multilingual Mode

Thu, 31 Mar 2022 22:03:00 +1100

A couple of days ago I started experimenting with Hugo’s multilingual mode . Basically, I had the idea of creating a version of this site in Ido – not translating everything, of course, but mainly things like photo posts, or simple anecdotes and things to exercise my command of the language. While I was at it, I also thought of making an edition of this site in Spanish, because well… I could probably use the practice in that too 😅 But TBH, I’m a lot more self-conscious about making posts in Spanish, even if I’m much stronger in it than Ido (with many more years of study, and especially serious study, under my belt). Part of me is afraid of looking stupid if I make any linguistic mistakes, and another part feels like there’s not really any point anyway because there are probably enough personal blogs already out there in Spanish for people who are interested in reading them. With so much more of a dearth of online content in Ido, plus my feeling that IALs like it and Esperanto are more forgiving of non-fluent speakers’ quirks, it just feels less intimidating.

Anyway, all my efforts are still lingering in an unmerged experimental branch of this site’s git repository, because it turns out there’s a lot I would have to do to get this project up and running. Lots of hard-coded stuff in my theme I need to make un-hard-coded, lots of strings I need to translate. Hugo has an i18n function which makes it relatively straightforward to provide translations for strings, but you still have to, you know, track them all down and replace them all with {{ i18n "translation key goes here" }} and add entries to your .yaml files with translations for each one.

Since 0.87.0, Hugo has supported a certain degree of datetime localisation (like you can set a date’s format to :date_long and it’ll produce “March 31, 2022” in English but “31 de marzo de 2022” in Spanish, for example). It seems to support a pretty wide range of languages but not, unsurprisingly, Ido. So, to support that I have to go back to the pre-0.87.0 strategy where you define translations for all the month names in your .yaml files in your i18n/ folder. (Note: If you do this, you need to define translations for English, as well.) For example:

# io.yaml
- id: January
  translation: januaro
- id: February
  translation: februaro
- id: March
  translation: marto
- id: April
  translation: aprilo
- id: May
  translation: mayo
- id: June
  translation: junio
- id: July
  translation: julio
- id: August
  translation: agosto
- id: September
  translation: septembro
- id: October
  translation: oktobro
- id: November
  translation: novembro
- id: December
  translation: decembro
- id: at
  translation: ye

# en.yaml
- id: January
  translation: January
- id: February
  translation: February
- id: March
  translation: March
- id: April
  translation: April
- id: May
  translation: May
- id: June
  translation: June
- id: July
  translation: July
- id: August
  translation: August
- id: September
  translation: September
- id: October
  translation: October
- id: November
  translation: November
- id: December
  translation: December
- id: at
  translation: at

The “id” can be anything, it doesn’t have to match the English text. You could make the ids “month01”, “month02”, etc. if you preferred. Anyway, once you have .yaml files with all this data for every language you want a version of your site in, you can print a long-form date in this very verbose way:

{{ .Date.Day }} {{ i18n .Date.Month }} {{ .Date.Year }} {{ i18n "at" }} {{ .Date.Format "15:04" }}

…and it’ll produce a string like “31 March 2022 at 20:15” in English and “31 marto 2022 ye 20:15” in Ido. (As an aside, yes, even in English I strongly prefer date formats that put the month in the middle, especially when unambiguous because letters were used for the month or because the order is yyyy-mm-dd.) So, that’s one thing that you might’ve thought would be difficult to customise for such a seldom-used language as Ido, but is actually quite doable. Unfortunately, there’s still lots else I need to do. Things like “Older Posts” and “Newer Posts” (I’m not even really sure how to translate “posts” into Ido; so far I’ve gone with “skribaji”, i.e. “writings”) and the names of every tag and category and the copyright notice and that little blurb about me that goes at the bottom of each post in my h-card… it’s just a lot, ok.

Another problem I encountered is that one guide to multilingual Hugo suggested defining a language-appropriate slug for each language’s version of a post or page (because your “About” page shouldn’t still be at about.html on a non-English version of your site, right?). However, in my config, I’d set it so URLs were generated based on the source files’ filenames, not any slug. I forgot why I’d done this in the first place, so experimentally, I changed it to use slugs. Quickly realised why it used filenames: all my microposts are titleless, and with no manually-defined slugs, that means Hugo thinks they don’t have slugs 🤦🏻‍♀️ so it tries to link to them just at, for example, 2022/03.html. Not sure why Hugo doesn’t eventually fall back to filenames for slugs, but apparently it doesn’t. Anyway, I guess I could work around this by manually specifying a post’s URL (like /io/2022/03/gidget-inspektas-buxo.html) instead of only the slug.

Anyway, idk, this is all clearly a lot of effort to expend on a whim. I have idly wondered whether I could more easily practise my Ido just by, like, setting up a dedicated Mastodon account or something. But honestly, I think I’d rather keep my efforts on my own site rather than on yet another Mastodon account I’ll forget to log into (I’m really bad at keeping more than one active at a time). Even though something like a Mastodon account would mean other people interested in Ido could reply to my posts, I guess 🤔 I guess the short answer is probably that yes, Mastodon would be easier but I just like the idea of posting on my own site more. #indieweb4lyfe

So, I feel like this post has been a rambling mess, but regardless, that’s where I’m at with that. Maybe one of these days I’ll actually have an Ido-language site edition to show you 😅 Until then, tinkering with my git repository it is – and if nothing else, this whole project has taught me much more about how to use git diff and git merge. So at least I’m learning transferable skills, hey?

Automatically Mark External Links in Hugo

Mon, 23 Aug 2021 23:55:50 +1000

Here’s something I have achieved today: I got my site to display an “external link” SVG icon at the end of all links generated from Markdown, using Hugo’s neat markdown render hooks . Basically, when Hugo is translating Markdown source files into an HTML built site, it turns Markdown links into HTML ones following a certain template – but by creating your own template at a specific location, you can tell it to translate them your way instead! So, I created a new file at /layouts/_default/_markup/render-link.html that goes:

<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}>{{ .Text | safeHTML }}{{ if strings.HasPrefix .Destination "http" }}<span style="white-space: nowrap;">&thinsp;<svg style="height: 0.7em; width: 0.7em;" focusable="false" data-prefix="fas" data-icon="external-link-alt" class="svg-inline--fa fa-external-link-alt fa-w-16" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><title>external link</title><path fill="currentColor" d="M432,320H400a16,16,0,0,0-16,16V448H64V128H208a16,16,0,0,0,16-16V80a16,16,0,0,0-16-16H48A48,48,0,0,0,0,112V464a48,48,0,0,0,48,48H400a48,48,0,0,0,48-48V336A16,16,0,0,0,432,320ZM488,0h-128c-21.37,0-32.05,25.91-17,41l35.73,35.73L135,320.37a24,24,0,0,0,0,34L157.67,377a24,24,0,0,0,34,0L435.28,133.32,471,169c15,15,41,4.5,41-17V24A24,24,0,0,0,488,0Z"></path></svg></span>{{ end }}</a>

What this does is, if the link destination begins with “http”, it appends this SVG from FontAwesome . I used the same technique I described here to embed the SVG directly in my code instead of through an <img> tag, so it can take on the colour of the rest of the link automatically. This also works only because I make sure to always use relative links to link to other pages on my own site – if I used absolute links, those would appear with the “external link” icon too. If I really want to link to an external page without the icon appearing, I can use the HTML <a href="">...</a> instead.¹ That’ll bypass Hugo’s markdown handling, so no icon will be added 🙂

Also note, I have adapted FontAwesome’s SVG code for my intended purpose… mainly I have:

added style="height: 0.7em; width: 0.7em; (so it appears at a suitable size inline)
added <title>external link</title>, as per CSS Tricks’ Accessible SVGs guide (title + desc tags are like the SVG equivalent of alt text apparently)
removed the aria-hidden="true" attribute, which tells browsers the element is purely decorative and neither has nor needs alt text (…because I added some).

I note this because under the terms of FontAwesome’s CC BY 4.0 Licence I am required to indicate any changes I have made to their work. I’m not sure whether that was intended to include tinkering with the metadata of the SVG but I wanted to err on the side of caution.

Important Note: If you just grab my code snippet above, you will also be bound to their CC BY 4.0 Licence! Click through so you know what you’re agreeing to, and make sure to provide credit to them for their free icon 👍 Outside of this post I stuck mine in the “site” section of my about page, which I think is an “appropriate” and “reasonable” place (as per the licence terms) to put it.

If you don’t want to use their icon, then of course, you can replace the entire <svg> tag in my snippet with whatever you like (and will not be bound to their licence). Your own icon, perhaps. Maybe one of Wikimedia’s “external link” icons (check the individual licences but some are GPL, some are CC, and some are public domain). Or you could replace it with a Unicode arrow, like ↗, or a text string like “[ext]”. The power is yours!

Another styling thing that I would note: I wanted to make sure the icon would always appear on the same line as the last word of the link, which turned out to be way harder than you might think it would’ve been.   didn’t work and in any case was way too wide, especially in Firefox where it was displaying as an em-space. My solution was to add <span style="white-space: nowrap;">  just before the SVG and </span> just after it. (Trying to end the span immediately after   meant the line would still wrap there in Safari.)   itself is a space that’s 0.2em wide, so there’s only a nice slender gap between my link text and the icon.

As for why any of this might be useful, mainly it’s for my personal wiki pages, to make it easier for people to tell when they’re clicking a link to elsewhere within my wiki as opposed to somewhere off-site. There might be some blog posts where making the distinction explicit could be helpful too, I don’t know. The point is: it seemed a potentially useful indicator 🙂

I can do this because I have my Hugo config set to allow “unsafe” markup in posts (which, contrary to the alarmist name, just means you can use HTML directly in your Markdown-formatted posts, which is explicitly allowed in Markdown specs like CommonMark anyway…) ↩︎

Mon, 23 Aug 2021 16:55:13 +1000

It’s been bugging me for a while that Vercel is generating incorrect “last modified” datetimes for my wiki pages on this site. What it seems to be doing is getting the last modified date only if it’s within the ten most recent commits. If the last modification was further back than that, it prints the last modified datetime of the tenth-most recent commit. From the docs it looks like Vercel is not even fetching git commit author dates (but commit SHAs and commit author logins, those it fetches…), so instead I guess it stores some cache that only goes back ten commits? I have no real clue, but because I don’t know how to fix this, I’ve commented out the part of my template that generated “last modified” text for my wiki pages. Better to display nothing than to have it display something that’s wrong for the vast majority of pages…

I mean… one way to fix this would be to build my site using GitLab’s CI/CD and just upload the built files to Vercel, instead of GitLab merely passing the source files along for Vercel to build. But ugh, what a hassle to change that all around 😩 Another strategy would be to manually set a “last modified” date in the front matter of pages I want to have one, and display that in preference to whatever git says. (Or even disable enableGitInfo entirely, if it’s just resulting in junk data.) That’d also be annoying, though. So, for the moment, I think just not displaying “last modified” dates’ll have to be the go.

Nord Dark Syntax Highlighting for Hugo

Tue, 17 Aug 2021 14:57:55 +1000

I said the other day that I would figure out how to customise the syntax highlighting for the Nord theme , and now I have. If you want to grab the stylesheet for yourself, I’ve uploaded it as a snippet on GitLab . Some quick usage notes (which you’ll find in briefer form at the snippet page, too):

First, make sure your Hugo config file sets the value markup → highlight → noClasses to false (default value is true). For example, if your config file is config.toml you should add:

[markup]
  [markup.highlight]
    noclasses = false

Whereas if your config file is at config.yaml, you should add:

markup:
  highlight:
    noClasses: false

Then, download that syntax.css snippet and add it to your Hugo project, probably in the same directory that you keep your other stylesheet(s).

Finally, add a <link> to the <head> section of your template pointing to where your stylesheet will be located on the built site, e.g. <link rel="stylesheet" href="/css/syntax.css">

You’re welcome to use it freely and change any of the values if you don’t like what I set them to, of course. I tried to base my choices both on the Nord theme’s own recommendations and on what different classes share the same colour in the default Hugo monokai colouring (e.g. by default NameTag and Operator take the same colour, so when highlighting HTML the same colour is used for HTML tags and the = signs between attributes and values). But it’s easily customised if you have a better idea 😊

Wed, 11 Aug 2021 15:34:33 +1000

Uhh, well here’s a little Vercel quirk to be aware of: its default build command for Hugo repositories builds all your drafts as if they were ready-to-go finished posts 🤯 It’s not like I had a burn book stashed away in my Hugo drafts or anything but it’s definitely something I wish I’d noticed yesterday! TBH it’s so random it hadn’t even occurred to me they could possibly be doing that – the “build drafts” flag -D is something you have to explicitly add to the basic hugo build command, after all. Fixed now, anyway.

Tue, 11 May 2021 23:50:00 +1000

I’ve run into more obstacles than I thought I would, but not only do I have an Indiekit Micropub endpoint up and running now (but not working for media uploads yet), but I’ve also set up continuous deployment with Github Actions, so my static Hugo site rebuilds after every new post. This guide here was really helpful for the Github Actions stuff, and the only reason I lost three hours of my life afterwards is that I missed the really critical information that it’s written assuming you haven’t set a custom value for publishdir in your Hugo config file. Whoops.

Anyway, I have more tinkering I want to do, but I’ve been staying up late night after night and it’s time I treat myself to getting into bed before midnight. My site will still be there to tinker on tomorrow, after all…

Mon, 10 May 2021 12:52:00 +1000

It’s been outwardly really quiet on this blog in the last few days, and that’s because I’ve been hard at work setting up Indiekit so I can post to here via Micropub (after my first attempt proved I am not good enough at programming to assemble an implementation by myself, even with loads of references 😂).

Once I’ve actually finished I might write up a longer post explaining how it’s all gone (because I’m sure it’ll be enthralling reading!). One thing I am really proud to have accomplished, though, is forking Indiekit’s Hugo preset and modifying it to generate my custom year and month metadata that I use to generate archives. Considering I’ve never written Javascript before, this was a huuuuge achievement for me. I still have a fair whack of stuff on my wishlist to work through, but the more successes I have the more confident I feel that I can get this working exactly how I want it 💪

Updating My Hugo Blog From My Phone

Tue, 27 Apr 2021 15:40:00 +1000

It is a truth universally acknowledged that an individual in possession of a Hugo blog must feel compelled to make loads of posts about every aspect of their Hugo setup, and I must admit that this instinct has not totally escaped me 😅 At least I write enough about other things to not be in the bottom-right corner of shame on this scatterplot . Today’s post is on something I’ve seen a lot of others grapple with too, namely the tension between wanting to use a static site generator to build a blog, cos it’s lightweight and avoids databases , while also wanting the freedom to update your blog on the go. This is particularly desirable for IndieWeb purposes, so that rather than tweeting on the go, for example, you can always post first to your own site.

There are a number of ways to do this. It seemed to me like the ideal would’ve been to create or adapt a Micropub server, so I could post to my blog from any Micropub client and have those posts translated into Hugo source files, ready to build. But currently, I do not have the programming knowledge to do this. Another popular workflow seems to be using Forestry.io or another CMS layer (even a Micropub server configured for this purpose) to manage Hugo source files stored in a Git repository, and hosting your site on something like Netlify or Digital Ocean’s App Platform so as to have it automatically rebuilt every time you make a new commit. If I were making a site from scratch that could’ve worked for me, but I already had conventional shared hosting and I was too lazy to move. So, I came up with another plan.

My alternate strategy is basically this: I keep a copy of my Hugo source files on the remote server itself, use SSH to create and publish new posts from my phone when need be, and use rsync regularly to make sure my remote copy and my local copy (on my computer) of my Hugo files are the same. For this, you will need to have or be prepared to get some kind of SSH app for your phone; on iOS I use SSH Secure ShellFish , which is a paid app (US$3/month or US$27 as a one-off purchase), but is very good with share sheet integration. Use whatever you feel comfortable with.

Updating my blog at home, from my computer, is very straightforward. I keep a terminal window open in my Hugo directory at pretty much all times, and whenever I want to, I can create a new post in pretty much exactly the way the Hugo Quick Start guide prescribes. To publish it, I could build the site locally and upload the built files, as the guide suggests. However, when I post from my phone I build on the remote server itself, so for uniformity I do the same from my computer.

What I do is rsync the source files, then SSH into the remote server to build there. I set up passwordless SSH and followed this guide to learn the syntax I needed for the rsync. I’ve created aliases – jls_put and jls_get – in my .zshrc file so I don’t have to type out the whole command every time (and risk making typos). Keep in mind the various flags you can use with rsync , and what makes best sense for you. I personally use the flags:

-auvzP: “archive mode”, don’t overwrite newer files, give me verbose feedback on progress, compress files for transfer, and give me a progress report – in that order
--exclude=config.toml: I have separate config.toml files for my local and remote Hugo directories because they’re stored at different paths on each filesystem; if I need to make changes, I make them manually to the remote file after testing locally
--exclude=.DS_Store: if you are on a Mac, these junk files will get sent across to your remote server if you do not exclude them with this flag.
--delete: only sometimes, so unlike the others it’s not in my alias! But I do use this with jls_put if I’ve just deleted a load of files I no longer need from my local copy; if I didn’t, they’d come right back next time I ran jls_get.

Once the files have synced (which only takes a few seconds after the first time, as rsync works incrementally), I SSH into the remote server (I have a four-letter alias to make this easy too), cd into the directory where I keep my Hugo source files (which is just under my home directory, so cd ~/hugo), and run hugo.

Posting from my phone is a little more of a hassle – more so than typing something quickly in an app and hitting “Send”, for sure – but is not completely unreasonable. The main issue is that obviously I don’t have Hugo installed on my phone, so I’ve got to create my post files manually. To help with this, I have a number of “template” files saved in my iCloud Drive. For example, my posts.md template looks like this:

---
title: ""
date: 
year: 2021
month: 2021-04
categories:
tags:
draft: true
---

…and to make it easier to post photos, I also have a photo-post.md file that has my image shortcode¹ pre-filled, like this:

---
date: 
year: 2021
month: 2021-04
categories:
- Photos
tags:
draft: true
---

{{< img src="filename.jpg" alt="" style="" width="" class="u-featured" >}}

So I duplicate this template to a new file, which for the most part I just have to use a Markdown editor to fill in the way I would any post on my computer. The big exception is the datetime, which I can’t autogenerate, so I have to type it in the exact format Hugo wants . If I want to post a photo, I also need to make a copy and edit that on my phone to resize it and strip out unwanted exif data. But I need to do that to post a photo from my computer, too. Overall, it’s mainly the datetime part that’s a pain compared to computer blogging.

To actually get my new post and any photos onto the remote server, I browse to their location in the iOS Files app, “share” them to my SSH app to upload them to the remote server, then open the SSH app itself, open the terminal on my remote server with one tap, and type cd ~/hugo then hugo. So long as I haven’t created a formatting error through sloppy editing, I’m done at that point. If I have, I fix my error then repeat the procedure in this paragraph.

For the moment, this process works well enough for me, even though there is still a bit of friction. It does the main thing I needed it to do, which is to let me post from my phone. It takes about five minutes for a quick text post, and maybe 15 for a photo post. It’s just enough of a hassle that I don’t do it unless I think my post is worth that kind of time investment, but maybe that’s a good thing – thoughtful sharing and all.

I mentioned it in passing in this post , but I have an image shortcode to enable responsive images, based on Laura Kalbag’s guide . ↩︎

Category-Specific RSS Feeds

Mon, 05 Apr 2021 21:21:00 +1000

Tonight I did something I’ve been meaning to do for a while – created a page outlining the RSS feeds for this site you can subscribe to. One thing I’m mindful of is that I post about a diverse range of stuff, and just because you might find some of it interesting doesn’t mean you care about everything… so I wanted to point out that the options are there if you want to subscribe to one or more specific topics (like pets, or languages, or “internet”, etc.), or if you just want to subscribe for articles and not all the “micro” posts, and so forth.

I’ve often actually wished social media worked more this way – that you could just have one user account and multiple “channels”, and you’d subscribe to individual channels of other users if they had them set up and not their whole account (unless you wanted to of course). Perhaps too complicated for anyone to have tried to implement? But the beauty of blogs with categories and RSS is that they can work that way 😉

The other thing I did tonight is changing the URLs for all my category and tag pages, so rather than being at e.g. /tags/cats.html they should be at URLs like /tags/cats/. Unfortunately I couldn’t find a way to do this by specifying permalinks in my Hugo config.toml 😒 so I had to create branch bundles for every category and tag and define URLs for them manually (although I could speed this up with archetypes ). All the subpages (like the RSS feed and pages 2, 3, etc. where paginated) were already under a /tags/cats/-style subdirectory so this just puts the index page in the same directory as all its subordinate content, which I see as more logical!

Using Taxonomies to Create Monthly Archives in Hugo

Fri, 02 Apr 2021 22:30:00 +1100

By default, Hugo doesn’t create date-based archive pages for you. And while it’s relatively straightforward to create an archive page that lists all the posts you’ve ever made (which is fine if you’re an infrequent blogger), it’s a fair bit trickier to make individual pages for each year or month of posts, as platforms like Wordpress create by default.

Since this serves as a microblog as well as a long-form blog, I knew when I shifted to Hugo that I wanted month-based archives. The easiest way that I found to do this is to leverage Hugo’s taxonomy system, creating taxonomies for months and year. My starting point was the information in this thread in the Hugo forums , but I’ve had to build on that and do some things differently to make it all work as I wanted. At any rate, my starting point to get the taxonomies existing was to specify this in my config.toml:

[taxonomies]
	tag = "tags"
	category = "categories"
	year = "year"
	month = "month"

At the start of every post (or really, any content that I want to appear on my archives page, including interactions) I have front matter specifying the month and year, like this:¹

year: 2021
month: 2021-04

Lest you worry that it’ll get really annoying manually typing that out every time you want to make a new post, actually I’ve set up my archetypes to generate that front matter for me, right under “date”:

date: {{ .Date }}
year: {{ .Date | dateFormat "2006" }}
month: {{ .Date | dateFormat "2006-01" }}

Like this, you will get list pages (the same view as on your homepage, or for a tag or category by default) at yoursite.com/year/2021/ and yoursite.com/month/2021-01/ (replace the trailing slash with .html if you’ve enabled “ugly URLs” like me). But that’s not what I wanted. I had already customised my posts’ URLs, so rather than going www.jayeless.net/posts/example-post.html they appear at www.jayeless.net/2021/01/example-post.html. What I wanted was month and year pages to match – so if someone just lopped example-post.html off the end of a URL, they’d get all my posts from that month, and similarly for year. Thankfully, in Hugo this is possible too, although it takes a bit more work.

What I needed to do was define a URL manually for each year and month. You can do this by defining custom metadata for each taxonomy term , which you do within the same /content/ folder that all your actual content goes into. Under /content/ you create subdirectories for month/ and year/, and under those, further subdirectories for each month and year (e.g. month/2021-01/,² year/2021/), and in each of those you need an _index.md file. (Note the underscore; it’s important to include it, or this won’t work.)

So for example, my /content/month/2021-01/_index.md file says:

---
title: "January 2021"
url: "/2021/01/"
---

Unfortunately, you do need to do this manually for every month/year, but the good news is that you can create them pre-emptively – pages shouldn’t be generated or get linked to until you actually have posts with that month or year. So it’s not like this is a job you need to remember to do the first time you post each month – you can do a stack of six months’ worth or whatever whenever it crosses your mind.

Anyway, so far so good! Like this, you’ll get a list page (a similar view to what you might have on your blog’s home page, or a category page) for each month or year, with a title of e.g. “January 2021” instead of “2021-01” for the months, paginated if that’s how your list pages usually work. At this point, you’ll probably want to create a “head” archives page, to link to all your newly-generated month and year pages (along with your tag and category pages, if you have those).

What I’ve done is create an archives.md file under /content/, but it’s really a dummy, all it contains is this (the “layout” part being most important):

---
title: "Archives"
layout: archives
---

Here you'll find all my posts gathered together by date, category and tag, for more focused browsing. You might also want to see [my interactions](/interactions/).

To actually provide all the taxonomy links (for time period, categories and tags) I have a /layout/_default/archives.html file. Mine (now)³ looks like this:

{{ define "main" }}
<h1>Archives</h1>
{{ .Content }}

<h2>By Date</h2>
<ul class="archives-list">
	{{ range $name, $taxonomy := .Site.Taxonomies.month }} {{- $cnt := .Count -}}
	  {{- with $.Site.GetPage (printf "%s" $name) -}}
          <li><a href="{{ .RelPermalink }}" title="All posts from {{ .Title }}">{{ .Title }}</a> ({{$cnt}})</li>
	  {{ end }}
	{{- end -}}
</ul>

<h2>By Category</h2>
<ul class="archives-list">
	{{ range $name, $taxonomy := .Site.Taxonomies.categories }} {{- $cnt := .Count -}}
	  {{- with $.Site.GetPage (printf "/categories/%s" $name) -}}
          <li><a href="{{ .RelPermalink }}" title="All posts in category &lsquo;{{ .Title }}&rsquo;">{{ .Title }}</a> ({{$cnt}})</li>
	  {{ end }}
	{{- end -}}
</ul>

<h2>By Tag</h2>
<ul class="archives-list">
	{{ range $name, $taxonomy := .Site.Taxonomies.tags }} {{- $cnt := .Count -}}
	  {{- with $.Site.GetPage (printf "/tags/%s" $name) -}}
          <li><a href="{{ .RelPermalink }}" title="All posts with tag &lsquo;{{ .Title }}&rsquo;">{{ .Title }}</a> ({{$cnt}})</li>
	  {{ end }}
	{{- end -}}
</ul>

{{ end }}

And put together, you can see what my archives page now looks like. If your posting frequency is such that “year” makes more sense here than “month”, you can do that just by changing the single word month in the code to year. Anyway, at this point – if you don’t mind your “month” and “year” pages having the same “list” view as your blog homepage – you can stop. But I wasn’t quite satisfied with this.

See, returning to the very first guide I linked here, I actually liked the “list every single post” style of archive page. I just didn’t want every single post ever to all be listed on the one page. I wanted the lists to be broken up by month (and year while I was at it, but primarily months). To do this, I needed to customise /layouts/year/list.html and /layouts/month/list.html. To show you what I changed, I’d like to compare my /layouts/categories/list.html and /layouts/month/list.html:

{{ define "main" }}
<h1>Posts categorised &lsquo;{{ .Title }}&rsquo;</h1>
<div class="h-feed">
{{ range .Paginator.Pages }}
{{ .Render "summary" }}
{{ end }}
<div style="clear: both;"></div>
{{ partial "pagination.html" . }}
{{ partial "h-card.html" . }}
</div>
{{ end }}

{{ define "main" }}
<h1>Posts from {{ .Title }}</h1>
<div class="h-feed">
<ul id="time-archive">
{{ range .Pages.Reverse }}
{{ .Render "li" }}
{{ end }}
</ul>
<div style="clear: both;"></div>
{{ partial "h-card.html" . }}
</div>
{{ end }}

That is, I made three main changes:

Told it to render the “li” view instead of “summary” (and added <ul> tags around the list items).
Removed the pagination (I want everything on a single page).
Told it to reverse the order of the pages (because the default is reverse-chronological, and for this I want chronological).

Then, obviously, I needed to make sure I have an “li” view. A simplified version of my /layouts/posts/li.html, stripped of anything that’s really extraneous to this guide, is as follows:

<li class="h-entry">
	<a href="{{ .RelPermalink }}" class="u-url">
		<time datetime="{{ .Date.Format "2006-01-02 15:04:05 -0700" }}" class="dt-published">{{ .Date.Format "2006-01-02" }}</time>:
		{{ if .Title }}<span class="p-name">{{ .Title }}</span>:{{ end }}
		<span class="p-summary">{{ .Summary | truncate 120 }}</span>
	</a>
</li>

And, well, you can see what my January 2021 archive looks like for yourself. It has some additional emojis and “micro post”, “photo post”, etc. prefacing the posts I haven’t given titles, but otherwise it looks a lot like the code snippet above.

So there you have it! This is the method I’ve used to create monthly archives for my blog in Hugo. It might seem like a lot of effort for something that other blogging platforms handle by default, but it works, and isn’t too much ongoing effort once set up.

Note the use of a hyphen as the separator instead of a forward slash for the month; this is to prevent a later step breaking. ↩︎
This is the thing that breaks if you use a forward slash as the separator. ↩︎
Previously I manually added links as new months and years started, having a top-level list for years and second-level lists for the months within each year. In contrast, the method I’ve provided here will keep the archives page updated automatically as new posts appear for each month (just like it updates the tags and categories), but it skips the year-level pages. At some point I had found a method to list all the years and months you had posts dating to (not necessarily that were in the taxonomies!), but I have a big backlog of book reviews that I hadn’t given the year/month taxonomies and thus I had a lot of broken links with that method. ↩︎

How I Integrated Webmentions Into My Hugo Static Site

Sun, 21 Feb 2021 14:55:00 +1100

Since I moved my blog over to Hugo, I’ve been wanting to do a little series of posts about various aspects of my set-up, just in case they help anyone else thinking of doing the same. This first post is about how I’ve enabled Webmentions , an important building block of the IndieWeb. As you might notice, my blog posts don’t have conventional comment forms underneath them. Instead, any comments you see displayed have been sent as Webmentions, meaning they’ve been posted elsewhere and syndicated here. But how did I do that?

Step 1: Set up IndieAuth

This isn’t directly related to Webmentions itself, but is a prerequisite for a few of the services I use, and generally good practice anyway. IndieAuth is an authentication system, which basically hooks into those “Sign in with Twitter”, “Sign in with GitHub”, etc. functions that you see around the web. To get it going, on your site’s front page you should link to different profiles you have around the web, either in the body (visibly) like:

<a href="https://twitter.com/thejayeless" rel="me">@thejayeless on Twitter</a>

…or in the head (invisibly) like:

<link rel="me" href="https://github.com/jayeless">

The important part is the rel="me"; that’s what tells the parser that you’re linking to the site because it’s your own profile, and not for some other reason.

Then, you need to make sure your profiles link back to your own homepage, too.

With that done, you should now be able to log into things with IndieAuth. You just type in your homepage’s URL, and IndieAuth will direct you to verify your identity by logging in with a service like GitHub or Twitter.

Step 2: Receiving Webmentions

While there are other options, like webmention.herokuapp.com , for this I decided to use Webmention.io , a free service from Aaron Parecki. To set it up, I logged into it using IndieAuth, and it gave me a little snippet of HTML to go in the <head> section of my theme to tell any prospective senders of Webmentions where to send ’em. The snippet includes your Webmention.io username in it, which would usually be your domain name, so for example, if your website was at example.com your include would be:

<link rel="webmention" href="https://webmention.io/example.com/webmention" />

With this include in place, any Webmentions to you will be sent to webmention.io and collated on their server for you. In fact, if all you want to do is see who mentions you, you can do that through the webmention.io interface. But assuming you want to actually display them on your site, there is another step.

Step 3: Displaying Webmentions

For this, I’m using a little Javascript include called Webmention.js . There are clear instructions at that link for how to integrate it, and it also comes with a webmention.css stylesheet so you can have something presentable without having to faff about writing the CSS yourself. Of course, I have tinkered with the CSS a little bit myself, because I wanted comments to display in full on my site and not truncate at the end of one line. Overall, I’ve found this to be a great solution for me.

Of course, before I moved my blog entries across I’d already posted a large number at Micro.blog, and got plenty of replies there. If possible I wanted to transfer those across, but I didn’t see how I could really re-send replies to the posts’ new locations, because they link to (i.e. are mentions of) the old locations. So in the end, I specified an old_url field in the front matter of every imported post, and in my Hugo template I include the following:

{{ if .Params.old_url }}
	<script type="text/javascript" src="https://micro.blog/conversation.js?url={{ .Params.old_url }}"></script>
{{ end }}

That is, “if old_url exists, run Micro.blog’s Conversation.js script to fetch the webmentions for old_url”. Hopefully Micro.blog doesn’t mind me using their resources this way 😃

Step 4: Marking Up Webmentions

So, receiving and displaying is only one half of the puzzle: realistically, you also want to send webmentions. And then, to make sure that webmention parsers actually understand what you’re trying to send, you need to make sure that your HTML is marked up correctly – basically to tell it what type of webmention you’re trying to send, what URL you’re sending it to, what the content is of your webmention (if it’s a reply), who you are as in what is your name, avatar and homepage URL, etc.

The handy guide I followed to set up my theme to do this is Aaron Parecki’s Sending Your First Webmention From Scratch . I don’t want to replicate all the content of that guide here, so I’ll just explain what I did in addition to that.

Firstly, I created a content type in Hugo called “interactions”, with templates to ensure that these are displayed (and sent) as replies, likes or bookmarks instead of the generic “mentions”. My “interactions” front matter includes the following possible fields (plus a few others that aren’t really relevant to this discussion):

response_type: for either “like”, “reply” or “bookmark”, which are the only ones I saw myself using. At the moment if I specify anything else it should fall back to just sending as a “mention”. I can easily modify my template to enable further types of responses if I ever feel the need
date: self-explanatory
link: the URL of the page I’m responding to
link_name: the name or title of that page
link_author: optional, but here I can specify the author of the page if I want
op, op_name, op_author: I haven’t needed to use these yet, but these are for situations where I’m replying to a reply on an original post, and want a Webmention to go back to that original post as well, so all the discussion can appear in one place
quote: also optional; this is if I want to quote something (like a bit I particularly liked, or a specific bit I want to reply to)

Then I’ve created a template – making use of Aaron Parecki’s guide that I linked above – to present that information in an intelligible way and also, behind the scenes, to be marked up with the correct classes so a Webmention parser can understand what parts of the page are relevant to it.

Step 5: Sending Webmentions

You can send webmentions manually, either from the command line or using a number of web interfaces. However, I wanted to automate my sending out of webmentions. For this, I decided to use Webmention.app . To get that up and running, I used IndieAuth to sign into – and get a token for – Webmention.app, then registered an account at IFTTT and created a “recipe” on there as per Webmention.app’s instructions. That means that IFTTT checks my RSS feed every hour for new posts, and if there are any, it makes a call to Webmention.app to check that feed for Webmentions and send out any that are there. I can also manually tell IFTTT to do a check, if for example I know I’ve posted something with Webmentions that I want to go out ASAP.

Bonus Round: Bridgy

I’ll probably talk a little more about Bridgy in a post down the line, about POSSE-ing , PESOS-ing and backfeeding more generally. However, because most of the webmentions on this site come via Bridgy, it’s worth mentioning here too.

Basically, Bridgy is a nifty little tool that, among other things, takes interactions with your posts (likes, replies, retweets/boosts) on social media sites like Twitter and Mastodon and forwards them to the corresponding posts on your own site, as webmentions. How does it know which posts correspond? Well, either your social media post can link back to your blog post, or your blog post can link to your social media post, with that link having to have a class of u-syndication. (You can also have both posts link to each other; it won’t hurt anything.) With a Bridgy account and those links set up, you can see that, for example, my review of The Fifth Season displays likes and a comment that I got on this toot linking to that review . If you like, you can also use Bridgy to automate the posting of those syndicated copies on some sites, just by sending webmentions to specific pages on Bridgy from any post you want auto-syndicated. For me this works well for Twitter, and no longer so well for Mastodon, for some reason. But still, overall Bridgy has really impressed me with just how much it can do.

My first blog entry on Hugo

Mon, 08 Feb 2021 16:21:01 +1100

Hello world! For a little while now I’ve been working on adding a blog to my Hugo-generated static site, and I thought it was about time to inaugurate my creation with an actual (public) post.

For the past three months I’ve been blogging diligently on Micro.blog , which incidentally is an awesome service I’d recommend to anyone who wants a lightweight, no-fuss, blog or microblog. The community there is wonderful, it has IndieWeb building blocks like Webmentions and POSSE built in, and the fact that it’s built on Hugo means you get a ton of flexibility to theme your blog as you like. Regardless of where my blog is actually hosted, I’ll be making use of Micro.blog and participating in its community for a long time to come.

That said, over the past few weeks I’ve been feeling increasingly inclined to incorporate my blog fully into my existing Hugo site. There are two main reasons for this:

The lesser, more theoretical one: A Hugo blog’d be easier to “export” and import if I had to. That is, because I already have all my Hugo files on my own computer (and saved to a cloud backup), if I wanted or needed to move to a new web host for whatever reason I could do so really quickly. Micro.blog has an export function but it basically gives you a single HTML page with all your entries on it. It’s clean, but would take a lot more effort to turn into a usable website somewhere else.
And the greater, more immediate/practical one: I want more control over how my photo posts are processed and displayed than Micro.blog offers, especially when photoblogging from my phone. Micro.blog won’t resize your image uploads, which is fine – I can do that myself before I upload. But then, by default your images get included into your post with an HTML tag with hardcoded width and height attributes – for my landscape uploads, this is 600x450 pixels. This is not the size I want my images to display, and this method of hardcoding the size also breaks on mobile, because the image stays 450px tall even when the displayed width is narrower than 600px, so it stretches. When I’m on my computer, I can work around this by saving the post as a draft, then immediately going in to edit the post. The iOS app doesn’t suppport saving drafts though, so I can’t really fix this before publishing on there. And then even if that was fixed I also wanted to use Hugo to generate automatic responsive images to optimise my site’s load times, which is an advanced kind of feature that I certainly wouldn’t blame Micro.blog for never introducing 🙂

Because I know there’s nothing anyone likes more than a Hugo-generated blog full of posts about the workflow of blogging on Hugo (I have a relevant meme scatterplot in mind that I now can’t find to link you to), I might publish further posts about the bits and pieces I’ve set up to make life easy for myself. This definitely isn’t going to become a full-time tech blog, though – I still have a lot more to say that isn’t just about the website itself 😊

I also, admittedly, still have a fair chunk of work to do to get this blog supporting everything I want it to. It should be capable of receiving webmentions through Webmention.io , but I haven’t yet set it up to display them. I also haven’t set up the sending of Webmentions, but Webmention.app should work. Integrating Brid.gy is also a possibility. I also need to tinker with my theme again and work out where I want my posts to “live” (the front page?). And I won’t fully switch from posting to Micro.blog to here until I know I have feature parity, at the very least. But the process is underway! And that’s the important thing.

Improving Load Times by Fixing My Images

Tue, 02 Feb 2021 22:59:35 +1100

As I mentioned in my post about Gemini, mine is a lightweight website for the most part; it’s built with a static site generator, I don’t use any heavy Javascript includes, and there are certainly no ads or trackers. The main exception I mentioned then was images: these were, by far, the major thing blowing out the filesizes (and loading times) of my pages and I knew there were improvements I could make to how I dealt with them. This is a post about some of the tricks I’ve learned, working on this over the last few days.

Lazy loading

Most of the things I’ll be talking about can’t really be done (or not so easily) on Micro.blog – they require a bit more control over how things are processed on the back end. This one, however, can be done. The principle of lazy loading is a simple one: rather than your browser loading all a webpage’s images at once, it should load them as they’re needed: when they’re currently on screen, or when you’re about to scroll down so they will be on the screen. If your blog’s front page has a long list of posts with relatively high-filesize images on it (like, ahem, mine), introducing this is a great way to save your visitors from loading megabytes of content if they never scroll that far down the page.

Until recently you had to use Javascript to implement lazy loading, and this is still the most flexible way to do it – lazysizes is one oft-used script. But most modern browsers (not Safari, alas) now recognise and will make use of a loading="lazy" HTML attribute to postpone loading certain images until needed. This is ludicrously easy to put into practice – every img tag you include in a post, just add that attribute to it, like you would alt text! This “complete guide” to lazy loading images has more information (including on Javascript options, if you scroll up) but it’s basically that simple.

One piece of advice you will see online is that the loading="lazy" attribute should not be applied to images that will appear at the top of the page (in the initial viewport). The thing with that is, there’s no real penalty to adding the attribute to an early-page image (the browser just ignores it and loads it anyway), and between pagination and single-post pages and so on, it would be totally unwieldy to try adding the attribute only to images that are at the bottoms of pages. My theory is: add it to everything I post on Micro.blog, and any milliseconds of delay will be made up for by the images that are never needlessly loaded at all 😉

Responsive images

So, this page is a thorough guide to how responsive images work . The idea behind them is also quite simple: your visitors might be looking at your site on all kinds of screen sizes, and to give them the best experience, you should try to serve them images that are roughly the size that will actually be displayed – not bigger (because then you’re wasting their bandwidth) and not smaller (so it looks crisp). So, you might have a single image in an array of different sizes, present that information to the browser, and the browser will load the most appropriate one for its current screen size at the time of viewing. Again, you don’t need any kind of sophisticated scripting for this – you can do it through regular HTML, specifically through the srcset attribute – check that link for an explanation.

Technically you could do this in Micro.blog… but you’d have to upload multiple copies of every image you want to post. So, I’ve focused my energy on implementing this change to my static site. Laura Kalbag’s post on processing responsive images in Hugo was very helpful for this. Basically I’ve declared images as “page resources” for my posts (book reviews, recipes, etc.), and then rather than calling that page resource directly in my template, I can resize it (multiple times!) and then call each of the resized images and pop the URLs in a srcset. Especially on pages with lots of images, this makes a huge impact. For example, each page of my book reviews had 20 different images on it, with a total filesize of over 900kB – not the worst ever, but it doesn’t even need to be that high! Now I’ve refactored all my reviews to make use of page resources, each page is now more like 400kB when viewed on a retina display – and 200kB on a regular display without pixel scaling. The best part is, I do not need to do any manual image-resizing myself – I can just chuck the full-size image in a folder with the post and Hugo does everything for me. It’s great. 😊

The `aspect-ratio` attribute

This one follows on from “lazy loading”, but it goes at the end of this post because it’s the thing I’ve learned most recently. Basically: if content hasn’t loaded and you scroll down the page, you might find elements on the page “jumping” about as earlier elements (like images) load and push the later ones out of place. To prevent this, you could specify a width and height and then the page will “reserve” that much space for the image before it actually loads and there’ll be no jumping about. But what if you don’t know the image’s size in advance?! My own layout, for example, has a main column spanning 90% the width of the viewport to a maximum of 800px. I can specify an image to take up 100% of the column, but then what do I put for the height? I can’t say what the height should be unless I know the width of the column – which I don’t.

The good news is that a new CSS attribute is coming to my rescue – aspect-ratio. Here’s a blog post about that , but fundamentally it comes down to: if I know an image is to be displayed at 100% of the column’s width, and I know its aspect ratio (like 4:3, 1:1 or 4:5), I can define both those things and the browser can use them to set aside the correct amount of space when loading the page. Et voilà, no more page-jumping!

The sad news is that this attribute is not yet supported in the current stable versions of major browsers (except Chrome for Android). However, it won’t break anything to start using it (browsers that don’t understand it will just ignore it), and once it is introduced, using it will help improve the experience of using your site in those times when things are still loading.

Conclusion

If you have a personal or a hobby site like mine, it’s pretty likely that images will be (by far) the biggest thing blowing out your file sizes and thus, your load times. This could get especially annoying for visitors with slow or unreliable internet connections, or strict data limits. Obviously doing an initial resize of your images (and not just uploading things at 4,000 by 3,000 pixels 😉) helps, but there’s loads more you can do. Lazy loading on long pages – so people don’t have to load content they never see – is a big help and relatively easy, while with a bit more effort (or some clever Hugo templating) responsive images offer massive savings. For me, while I know my humble site is far from the worst offender on the web (how about those sites that never finish loading because they have scripts constantly doing shit in the background?!), I do feel proud when I see my webpages getting leaner and faster. To me, that kind of efficiency is how the web should be. Sharing my thoughts, my photos, and stuff I think is cool is great – but even better to make sure I’m providing a great viewer experience as I do so 😊

Fri, 04 Dec 2020 20:49:11 +1100

Today I started teaching myself how to use Hugo! The Quick Start guide on the official site is indeed a good quick start, but if anyone else needed a more detailed guide to how to actually get up and running, I can recommend Make a Hugo blog from scratch .