Uprooting the blog again

by AJ "Tyron" Martinez @ worldsbe.st • February 23 2021

Medium → Ghost → Jekyll → Hugo. Whether I’m actually getting any extra writing done is unclear.

I switched away from Jekyll because the build times were getting to me, because Ruby is scary and fucked up, and because the old layout I’d designed wasn’t really doing it for me anymore—too much weird layout hack shit, and I wanted to go for something simpler. (Plus I’d namespaced all my CSS for reasons that made sense at the time, and looking at classes like .postfooter-spooby was slowly driving me insane.)

As part of my continued principle of reducing friction, I figured it was time to spend a day or two to make sure I wasn’t working with tools I hated. As it turns out, when your static site generator actually has functioning live reload, debugging and layout work is a lot easier. :D?

Notes for anyone else making a similar migration:

There is an official migrator that will handle your post content, but nothing else. Start there and be prepared to do some extra work.
If you’re looking for some concept of unlisted pages, it probably seems obvious to roll your own template for it, but setting a page’s build options to list: never does just as well. This also works if you don’t want a content type’s index page to appear in a listing, and you can cascade it from an index page to affect every page in that folder.
To avoid breaking permalinks, I just chopped off the first 11 characters of every filename (YYYY-MM-DD-), then set permalink format to "/:filename". Similarly, to avoid breaking RSS, baseName: feed worked well enough (probably).
If you were using includes to avoid boilerplate in articles, the matching Hugo concept is “shortcodes”. Protip, you can enclose arguments in backticks to avoid the single-vs-double-quote nightmare that happens when you try to find-and-replace these.
SCSS works (and is my one concession to preprocessor bullshit, god it’s so cozy), but you need to be using Hugo Extended; place it in your theme’s assets folder, then include it using something like:
```
{{ $style := resources.Get "style.scss" | resources.ToCSS | resources.Minify | fingerprint }}
<link rel="stylesheet" type="text/css" href="{{$style.Permalink}}">
```
Stuff in themes/your-theme/static/fonts will end up in /fonts in the final build (fonts is just an example here). This seems basic, but I had a static directory in the tree already and got super confused for about 10 minutes.
Hugo doesn’t do full-text RSS by default; it’s a pretty simple adjustment, but hopefully it’s exposed in a better way than “literally redo the template” in the future. Fortunately, RSS is old as fuck and deader than I’d prefer, so it seems like a change that only needs to be made once.
hugo serve won’t hot-reload if your page doesn’t have a <body>, and won’t update correctly if you delete a file after it’s been rendered—you’ll need to restart the server to see that file disappear. This is probably the most significant pain point when setting things up.

For those of you that don’t care about the technical details, uh, how did you make it all the way down here? Regardless, all of the writing here should be pretty much the same. KAC2020 writeup still coming, this just felt like a required upgrade considering how much of a Large Thing that particular article is.

Mind the dust. Let me know if anything seems like it’s out of place or could use improving.