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.
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 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).
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.
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.
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
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.
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.
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.
I don't know why Hugo has no migration til like Go to deal with this.
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.
Sometimes Software is Done, or Why Hugo Why (2024)
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.
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.
Same. We have a an org. that is still on version 6 because of this. Never again.
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.
In open source projects it’s really hard to have all major contributors agree that all their work is good enough for a 1.0z
Herding cats and all that.
Also version numbers are kind of meaningless. “1.0” would better be saved for a big marketing push.
> Also version numbers are kind of meaningless.
Have you heard The Good News about the Semantic Versioning?
https://semver.org/
I have, yes, but I’ve seen precious few projects actually follow semver.
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…
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.
in semver, if your major version is 0, then any change can be breaking, which, imo, is why semver projects stay pre-1.0 for so darn long.
So even with semver, pre major version 1 is pretty much meaningless.
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!).
This suggests that "strong opinions, loosely held" makes for a poor software development philosophy.
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
https://www.11ty.dev/blog/stability/
This is JavaScript, npm rot is a huge problem in its ecosystem.
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's horrendous backwards compatibility story made me so angry I switched to a homemade solution using SSG for my personal site.
https://romanzolotarev.com/ssg.html
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.
Oook. I have seen worse. Its been my experience that the documentation is pretty good and the community helps when when there are discrepancies.
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.
> I could have just built my own SSG
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...
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?
oh sorry there is no example section. just search github for examples.
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).
This is one of those things that would have been great to know before adopting Hugo. But alas.
Isn't this a very common criticism of Hugo so that it's easy to learn about when choosing? (though a prominent note in the readme would be nice)
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
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
If anyone has used both Hugo and Zola, I’m curious to know if you think Zola works better. I’m trying to decide which one to utilize.
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.
Zola is infinitely better for templating alone. It does everything Hugo does.
Zola seems to be a wedding planner... so a completely different thing!
https://github.com/getzola/zola
Regarding smart quotes: To each their own, but IMHO it’s better to just hard-code the desired quotation marks, like this:
To me, this is the beauty of UTF-8.I am sorry, but I hate Hugo.
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.
I’m still running a site on Hugo 0.18.0 because it works and the effort involved in upgrading is not worth the benefit.
And that is the appeal of Hugo. A single binary with no dependencies that still works years later.
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.
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.
https://www.docsy.dev/
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
this is why people write their own static site generators...
> the grep 31m|32m thing is searching for red/green text in the diff
This is a cool trick!
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.
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).
Agreed. Astro seems more of the same as Hugo, except JS-based. Note that for its intended audience, this is a feature.
Because the language here is unclear, Jekyll is not deprecated. It is still making releases (4.3.4, a few weeks ago)
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.
Wait until I break the news about 90% of the tools in the Linux world.