RE: Really getting started with Hugo

a reply to Bryce Wray’s post about Hugo’s quickstart instructions

Tue, 19 Jul 2022

I was lurking on HN and saw a post by Bryce Wray about a better way to get started with Hugo, a high-performance static site generator. It comes a bit too late to be useful to me now that I’ve got pblog set up the way I like it, but I thought I’d share it anyway because it touches on one of the snags I encountered when tinkering with Hugo.

Here’s a 50,000-foot view of how I think a new Hugo user should get started:

  1. Install Hugo.
  2. Use a one-line Hugo command to create a Hugo project.
  3. Add a minimal number of bare-bones files so the project can generate a working website.
  4. Use another one-line Hugo command to run its development server, so the user can see how the website looks.

And that’s really it. But the current process omits Step 3, and that’s a show-stopper for most new folks. Instead, Hugo’s “Quick Start” documentation tells you to install a theme, almost as “training wheels” for one’s “ride” with Hugo.

Here’s the deal: most Hugo themes are almost as complex as WordPress themes despite not using PHP. Customizing them is a huge pain in the ass when all you want to do is make a motherfucking website that has more than one page and provides modern amenities like consistent navigation and a RSS feed. Telling people new to Hugo to start by installing a theme is definitely a mistake. At least Jekyll provides a reasonable1 default theme.

I have got admit that I liked this little note before the improved instructions.

The following instructions are for only the two major computer operating systems for consumers, Windows and macOS, because I frankly doubt Linux users need help.

Being a Linux user for almost a quarter century (since 1998), I might indeed not have needed help, but I might have appreciated it anyway. I know some techies think that their expertise as engineers transfers into a wide variety of unrelated disciplines2, but I’ve found out the hard way about assuming that unfamiliar tech is easy for me to use because I’ve managed to get Slackware running on a secondhand Thinkpad. It’s often a good way to end up embarrassed.

  1. for certain values of “reasonable”, given that anything billed as “one size fits all” is lucky to fit most↩︎

  2. something you can see in action on Reddit and Hacker News↩︎