Skip to main content

Configuring Hugo

··1245 words·6 mins
Blog Configuration Personal
Author
Moulting Penguin
Table of Contents

Intro
#

It’s unclear when I want to use this site for (personal notes, random writing, some form of actual projects). My projects tend to be personal projects, and something unlikely to be helpful to other people. This is an example of the latter.

To be clear, this actually should be a post, but the reason I’m making this a “project” is because without having at least one project, you end up with weird empty boxes on the website, and I find that aesthetically displeasing. So I’m writing this up as a project.

Setting up Hugo is pretty easy, but then you start to find little things. This is (hopefully) a place to keep pointers to these little bits of info.

Here I have the things I want to call out, or remember. I would use a table of contents, but this theme only has ’toc’ on posts, and, well, this is a project.

Configuration
#

This is random configuration bits.

Start with the default/examples
#

Hugo Liftoff comes with three config files in the exampleSite config directory:

  1. hugo.toml - Everything not in the other two files?
  2. menus.toml - The menus to present in the top right corner
  3. params.toml - The basic parameters of how we config Hugo.

I do actually believe we could combine them all into one file. But it was handy to keep them this way.

So I started by using these configs, and modifying to my needs. It’s pretty straightforward.

Customize for my environment
#

So I wanted to be able to author on my laptop, then publish to the VPS machine. This fits in well with the paradigm of author/review/publish. I can author using my favorite editor, review using my laptop on a “private” web server (something I prefer to do over running hugo as a web server), then publish to the VPS. To do that, I created a Makefile with a few targets, and tell hugo which environment to use. Each environment reads overriding configs.

There are really only a few configs I muck with:

baseURL = 'http://localhost/path/'
buildDrafts = true
cleanDestinationDir = true
publishDir = 'path'
  • baseURL - I only change this on the development config
  • buildDrafts - True on development, false everywhere else (default and production)
  • cleanDestinationDir - True in development and production, false in default
  • publishDir - I set this in production to have a clear separation between what is to be published and everything else.

I also have targets on the Makefile to copy the bits to the VPS and/or open a web browser pointing to the relevant location.

Unsafe Markdown
#

The demo site uses some snippets that require turning off “safe” rendering in the hugo.toml file. This means if you want to do some of those things, you need to change the default from false to true:

[markup.goldmark.renderer]
  unsafe = false

It’s annoying that the ‘default’ site needs configuration changes to work, but what can you do? Also, I turned it on in the demo site, and now I can’t recall what breaks. I think the stuff under “Other Elements” like abbr, sub, sup, kbd, mark.

Usage
#

It’s still early days (obviously). While I created the site a while ago, I only had the ‘about’ and first post up, and in the middle of putting up this ‘project’, I got distracted by life. Barely a month after I did the first commit on this site (Wed, 16 Aug 2023), the author of Hugo Liftoff committed their Theme support EOL notice, and that was 4 months ago. I don’t get to updating themes and writing much, so it’s telling that the day I actually dropped the files on the VPS was a day after the theme was deprecated. :-( I’ll probably write a post about that problem “in tech”.

So mostly it would appear that there are three parts to using Hugo:

  1. Create “content” (hugo new ...).
  2. Review your changes until you’re happy with it 1
  3. Publish

It should go without saying that “content” can be “updated” as well as “created” (which I’m actually doing right now, as it happens).

Missing Things
#

This is just a list of crap I’ve encountered that I don’t (yet) know how to do. As I discover them, I’ll update this list.

  • using images inline I learned about the figure shortcut. See About This Site.
  • See the git revision date on the posts (I’ve seen other sites do this, but can’t quite figure out how to do this yes). I mean on the actual page. Blowfish does this.
  • Try out some of the other Markdown (Goldmark) syntax/options.
  • Maybe learn how to make some shortcuts of my own It’s pretty straightforward, it turns out. :-)
  • Eventually either make my own theme or do away with it. I dunno. But there are SO many themes, and it’s like all these thousands of themes are basically people’s personal themes they worked on and decided to publish. So why not make my own? No one wants to run their own server. :-) So let’s just use an established theme.

Theme Support
#

One of the more fun aspects I’ve learned about Hugo is that everyone is doing their own thing, or relying on some “major” themes. Of those doing their own things, some release their themes after they’ve decided to abandon them. Some support their themes while they’re using them, but then for one reason or another, quit. This happened with Liftoff. It seemed like a reasonable theme for me to start with. But then after about 3 months, I noticed the only commit was an update saying “I’m no longer going to update this theme”. Well, OK. But then a month later a spurious brew update/upgrade command and POOF! Hugo couldn’t build this site.

Sigh.

I’ve often complained of the lack of people willing to do their own thing, and that they should, for example, run their own mail server. But as Moxie Marlinspike said, way more eloquently than I, “People don’t want to run their own servers, and never will.”. Ayut. But man, Hugo themes? People go wild. Just look at the complete list of Hugo themes. How do you choose one? Clearly, you want one that fits your desires (maybe you want ads, or what a lot of JavaScript goodness, or maybe something focused on <insert thing you like>). Maybe you think about support. Maybe you don’t care. But you should.

It turns out Moxie is completely right. Not about running their own server (at least, not SPECIFICALLY), but about tool usage. You could make your own chisel. But would it be better than a chisel you can get at the store for $5? I doubt it. I have come to the realization that there is a trade-off people make between functionality and ease of use. Perhaps this would be better for it’s own post. :-)

The point is, I bailed on Liftoff because it doesn’t work anymore, and isn’t supported. So I moved to Blowfish. And despite the failures when I first tried it (before Liftoff), having used Liftoff, well, it taught me enough about Hugo to make Blowfish quite usable. So there you go, not I’m using Blowfish.

The only other alternative is to make my own theme. But you know how that is. No one wants to run their own server, and I don’t want to craft a theme from scratch (and maintain it).


  1. Art is never finished, it’s just abandoned. Or so I’ve heard. ↩︎