Some Notes on Upgrading Hugo
jvns.ca
jvns.ca
A static site generator that has somehow managed to be more inconvenient than many CMSes.
https://commaok.xyz/post/on_hugo/
> When I first used Hugo I loved it. It was fast. It was simple. It just worked, as much as any software does, and it solved a real problem.
> It was done.
> But people kept working on it.
> I’m sure that it has been improved in countless ways. But along the way it has gotten bigger and more complicated, and has broken backwards compatibility repeatedly.
Hugo is one of those tools that seems to have a forward compatibility issue and a lot of rot happens to your sites theme without a bunch of work. Can't say I am a big fan of that I mostly don't want to have to deal with these sorts of problems on a static site generator.
People in the comments as well as Julia in the article are mentioning breaking changes. I would imagine committing to a stable API and signaling this through a v1 release would show respect to the time of your users.
Herding cats and all that.
Also version numbers are kind of meaningless. “1.0” would better be saved for a big marketing push.
Have you heard The Good News about the Semantic Versioning?
The Linux kernel, for example, explicitly states that version numbers are meaningless.
In my experience, semver ends up just being more of a reason to never have a major release rather than a way to communicate breaking changes.
I don’t think Hugo uses semver anyway…
It works really well for libraries and APIs, but in my experience it doesn't work well for end-user-facing products. If you look at npm packages, a lot use semver.
So even with semver, pre major version 1 is pretty much meaningless.
This is coming from a Go dev who understands Hugo's internals quite well and uses it in production.
Had I known what my journey with Hugo would be like, however, I would have never touched it. In all that time, with all the headaches it caused, I could have just built my own SSG.
I don't know whether I have seen worse. I may have seen 'equally bad', however.
There's a good chance that I'm just not good at understanding that style of documentation. I feel there is a huge lack of examples. The examples given are very specific and they do this thing where, when showing two examples of the same functionality, they change all the variable names and data-structures, making it impossible to follow.
But that may just be me. Some people might find it useful to see the same example with different data-structures and variable names.
That's actually what I did when I tried using Hugo. Go is very well suited for it.
https://github.com/darkfeline/felesatra/blob/master/kanade/c...
I tend to forget which Hugo version I've used before for a site template that I end up reusing, so I just downgrade Hugo versions until the site finally builds — the saving grace is that every version is its own binary, and there's no dependency hell like some other JS-based static site generators I've used (I'm looking at you, Gatsby!).
Anyhow, regarding this:
> 4.3: nested lists sometimes need 4 space indents
Can be prevented by using a formatting style that always works with lists and blockquotes and makes it easy to see nesting: https://jmmv.dev/2022/07/markdown-lists.html
My go-to meme has been "The most difficult we do at this place is formatting documentation".
I can go 10 iterations just to get an image link or internal reference right.
And the fact that I would like my .md files to look at least ok in github as well as Hugo makes me scratch my head. If I want an inline image I use two references. One for github and one for Hugo, where one reference is broken in the other. Looks ugly but at least it works.
Not to mention panels. The mix between Hugo's markup and markdown markup. The chosen markup dialect. Errors because of missing Hugo headers.
And there is no regression testing. It can take 2 years for one of my product managers to notice that the link is broken. When she most needed it.
Yes, I am probably holding it wrong. Please make me feel good.
And that is the appeal of Hugo. A single binary with no dependencies that still works years later.
“Oh, *interesting*!”
If anyone wants simple, I think Eleventy is the way to go.
I've finally been exploring Astro recently, and apart from Astro-specific features like Content Collections, everything else seems fairly stable, or at least unopinionated the way Hugo is (except Hugo changes their opinion far too much).
This is a cool trick!