If you are experiencing frustration with Hugo templates, here’s what I know so far#

Unlike a recipe blog that tells you a long story about studying abroad in Europe before giving you the recipe, here is the TL;DR up front:

1. Running the Hugo test server doesn’t actually do anything. Yes, it runs a test server and serves pages on your workstation. But it doesn’t actually make the site. Once the test site looks good, terminate the server and run the Hugo command with no options. Then deploy the public folder.
2. Hugo doesn’t like when you add multiple MarkDown files to the site. Work on one at a time. Also, keep a backup copy of your content files outside of your main branch in git. I have broken things so badly that it’s easier to just start over from scratch with a new git repo.

If you are interested in the tale of this quest for this knowledge, please read on:

This is a story about what happens when a system adminstrator attempts web development.#

It is my opinion that it was easier for develpers to invent Docker than it was to get sysadmins to play nicely with them. As an infrastructure dude, developers are kind of weird. Deploying apps with Docker feels really weird. Using automatically generated network configurations and firewall rules feels reckless. Like driving without a seatbelt. If you were to ask a sysadmin to build you a system for deploying apps, you would get Linux Containers. LXC isn’t weird. If you asked a developer to build you a system for deploying apps, you would get Docker. Infrastructure as code feels like an uneasy peace between two enemy factions.

It won’t last. Sysadmins and developers are natural enemies! Like users and devs! Or hackers and devs! Or managers and devs! Or devs and other devs! Damn developers! They ruined development!

The tragedy of Hugo#

Hugo is a great tool. Zero shade on the folks that are developing it. The locus of my problem is trying to learn all aspects of the web stack all at once. It’s frustrating to say the least. I have also not yet figured out a workflow for blog posts. It’s a chicken and egg problem. Building a website, for me, is strange intersection of design and development, two things I know nothing about. I gotta futz with the colors and the layout while also futzing with code and file structure. Also, I have no idea what the site will look like until I have actual content. So, which step do I take first? All of them! I go around in circles fiddling with design, code, and content. For quick placeholder content, I took my inspiration from The Shining:

All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy. All work and no play make Jack a dull boy.

For quick placeholder designs, I thought I was gonna slap down a Hugo theme and move on. NOOOPE! Hugo themes do not behave consistently for me.

Hugo confuses me first by looking like a Unix utility, but actually being a dev tool. What I mean is, it looks like sed but it behaves like git. It can produce a lot of files, but it can only ingest one new MarkDown file at a time. This is a critical lesson to learn because I can get a theme working with some quickstart guide, then toss in my MarkDown files and the whole thing fails to update.

Hugo confuses me secondly by being under constant heavy development. If I run a version of Hugo on my laptop, and then a different version of Hugo on my web server, calamity ensues. I think this second issue severely affects my ability to learn Hugo themes. Theme developers post documentation for their themes, but it’s often out of date. These guides often document features that have been deprecated, so your theme breaks. Also, every theme seems to be wildly different, configuration-wise, from the next.

It seems to me that every person who learns to use Hugo gets fed up with making other people’s template work and fork it to make an “easy to use” (natch) template of their own. The result is a theme that for reasons unknow to me will include links to some dude’s Twitter page but not to my Mastodon page. This means that my path to learning is beset by inconsistent behavior in the resulting website.

Hugo is probably still worth it for me#

It bears repeating that all of my issues here are taking on learning Caddy, git, Hugo, Hugo themes, and MarkDown all at the same time. Once I feel comfortable creating content with Hugo and I settle on a theme that behaves consistently, I will move on to the deployment portion of the workflow. Right now I am copying files with WinSCP like it’s 1995.