> 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 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.
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
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 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.
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).
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 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.
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 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
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.
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
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.
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 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.
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
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.
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.
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).
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/
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 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.
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.
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.
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
> the grep 31m|32m thing is searching for red/green text in the diff
This is a cool trick!
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.