I use Hugo for my site, and the willingness to break the API despite the age of the project is definitely my least favorite feature. So I’m running a years-old version because I don’t do anything interesting with formatting.
Yeah, I adopted Hugo and now I regret it. Every release seems to break themes, and many theme maintainers give up trying to keep current, so if you use someone else's theme you're running a small intersection of hugo versions and can't rely on packaged releases.
A static site generator that has somehow managed to be more inconvenient than many CMSes.
> 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.
I have had the same problem with hugo upgrades. A few tweaks here and there to the template and then found the problems became too great to bother and ended up replacing the entire theme. Even though the new theme was up to date about 5 minor versions ago its already throwing a couple of warnings.
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.
This is every site generator, templating system, or CMS I've ever used. Do you know why Drupal can't get people off of version 7, even though versions 8, 9, 10 have come and gone? Because too much stuff is different and the project didn't provide any easy migration path. Too much churn will kill your project. Even if the changes are theoretically or technically improvements, users will refuse to adopt them, and those who went through it will never consider using your software again. I know that Drupal is on my permanent "never touch this" list and I used to be a pretty happy user and even something of an evangelist for it.
I wonder why Hugo is still on a <1 version. It has existed for 11 years now. Is it really so hard to design a stable API for themes and content?
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.
Precious few? The entire PHP, JS/TS, and parts of the Python ecosystems are built around Semver. That’s millions of projects. Maybe you’ve just looked in the wrong place?
They are meaningless for projects like the linux kernel. The linux kernel has no stable kernel API and they aren't supposed to break userspace. There's not that much to semantically version without a stable external API.
Projects using semver try not to do breaking changes, which is why they don't change major versions often.
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.
I built my new site (https://varun.ch) using 11ty, because they seem to commit to never making breaking API changes. They have a YouTube video where they build a pre 1.0 project in 2.0. https://youtu.be/bPtQmsjXMuo
Definitely agree. But 11ty’s core dependencies are relatively small (compared to other NodeJS things), and I am personally contributing PRs for getting rid of some long ljharb-y dependency chains.
Hugo might have the worst documentation I have ever encountered in the wild.
Which, if you think about it, is the height of irony. Hugo, the thing so many people use to make documentation, has terrible, terrible documentation. It is impenetrable.
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.
The community is very good indeed. That was always where I ended up finding answers.
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.
It’s pure bliss compared to just about any Python library. Oh, you want to know what arguments this function takes? Well, a kwargs dict, duh! Why not just read the full example section to hopefully find some of them?
Thankfully with hugo there is documentation, old releases etc. For some of my old JS projects I can't do anything but rewrite. Packages disappeared, documentation too (some of it is on archive thankfully).
My take on Hugo is that it tries to be opinionated, but changes its opinion far too much. This doesn't seem to happen with other static site generators like Eleventy, and maybe Astro (I haven't used Astro through enough upgrades to provide a good opinion).
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!).
I also use Hugo and upgrades scare me because it’s really hard to tell whether something has subtly broken or not. Also, the documentation is inscrutable. But it’s fast and already in place, so hey, I keep using it.
Anyhow, regarding this:
> 4.3: nested lists sometimes need 4 space indents
For a simple use case (simple site with a simple blog), I started off with Hugo and found it too complicated, then switched to Zola and had it done in a few days. The documentation was simple and to the point, the templates were easier to work with (for me). The community is infinitely smaller though, if it's not in the docs you're basically on your own.
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.
Thanks for posting this. I love Hugo btw, its been a great SSG for me. I have been putting off a 0.42 upgrade for a few years now. Wanting to use the new markdown renderer at some point. But I am using the Academic theme, and not wanting to code a new theme or migrate my current theme just yet. Paying someone to code the theme is a good idea.
Thanks for sharing. Last time I updated the hugo version I built my site with, it was indeed a good few hours of altering the template customizations I had made. Luckily as someone else on here said, having lots of documentation available was a lifesaver. Still, not sure I intend to update again anytime soon! haha :P
If possible, don't use Hugo directly. Use docsy. I've been using docsy for many years and it really simplifies a lot of things while retaining the options for you to dive deep as needed.
I wanted to migrate away from my Jekyll website but Hugo was a mess back then. Unintuitive, weird syntax, weird logic. This was years ago and my Jekyll blog still runs perfectly. I'm gonna migrate or to Astro sometime as Jekyll is deprecated
I migrated from Hugo to Astro and by that I mean I had to basically start from scratch. I'm using it but suspect Astro will be the next Hugo in a few years time. It is not overly simple in any way.
> I'm using it but suspect Astro will be the next Hugo in a few years time. It is not overly simple in any way.
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).
I guess software is never done, but Jekyll is over 20 years old at this point. That is a long time to still be iterating on a Markdown to HTML converter.
My hacky variation of this would have been to create a git repository inside the generated html folder. Commit the legacy output. Build the new release and then you can use git to inspect the changes. Even commit away the irrelevant differences so only the broken deltas are highlighted. Iteratively edit the markdown until git reports no changes.
