[HN Gopher] Some Notes on Upgrading Hugo
___________________________________________________________________
Some Notes on Upgrading Hugo
Author : ColinWright
Score : 73 points
Date : 2024-10-12 20:52 UTC (1 days ago)
(HTM) web link (jvns.ca)
(TXT) w3m dump (jvns.ca)
| joeblubaugh wrote:
| 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.
| guideamigo_com wrote:
| I don't know why Hugo has no migration til like Go to deal with
| this.
| ta988 wrote:
| 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).
| varun_ch wrote:
| 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/
| guideamigo_com wrote:
| This is JavaScript, npm rot is a huge problem in its ecosystem.
| varun_ch wrote:
| 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.
| PaulKeeble wrote:
| 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.
| SoftTalker wrote:
| 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.
| trinsic2 wrote:
| Same. We have a an org. that is still on version 6 because of
| this. Never again.
| amatecha wrote:
| 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
| fifilura wrote:
| 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.
| pityJuke wrote:
| This is one of those things that would have been great to know
| _before_ adopting Hugo. But alas.
| eviks wrote:
| 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)
| SPBS wrote:
| 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.
| ufo wrote:
| > the grep 31m|32m thing is searching for red/green text in the
| diff
|
| This is a cool trick!
| 3eb7988a1663 wrote:
| 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.
| imron wrote:
| 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.
| edem wrote:
| 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
| beardedwizard wrote:
| 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.
| runjake wrote:
| Agreed. Astro seems more of the same as Hugo, except JS-
| based. Note that for its intended audience, this is a
| feature.
| runjake wrote:
| Because the language here is unclear, Jekyll is not deprecated.
| It is still making releases (4.3.4, a few weeks ago)
| 3eb7988a1663 wrote:
| 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.
| CrimsonRain wrote:
| 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/
| DandyDev wrote:
| 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.
| dartos wrote:
| 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.
| Cheer2171 wrote:
| > Also version numbers are kind of meaningless.
|
| Have you heard The Good News about the Semantic Versioning?
|
| https://semver.org/
| dartos wrote:
| 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...
| gregmac wrote:
| 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.
| johnny22 wrote:
| 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.
| 9dev wrote:
| 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?
| jmmv wrote:
| 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
| newman314 wrote:
| 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.
| tga wrote:
| 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.
| snarkyturtle wrote:
| Zola is infinitely better for templating alone. It does
| everything Hugo does.
| threemux wrote:
| 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
| throwaway77385 wrote:
| 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.
| trinsic2 wrote:
| Oook. I have seen worse. Its been my experience that the
| documentation is pretty good and the community helps when when
| there are discrepancies.
| throwaway77385 wrote:
| 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.
| Ferret7446 wrote:
| > 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...
| 9dev wrote:
| 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?
| cpach wrote:
| Regarding smart quotes: To each their own, but IMHO it's better
| to just hard-code the desired quotation marks, like this:
| "Oh, *interesting*!"
|
| To me, this is the beauty of UTF-8.
| trinsic2 wrote:
| 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.
___________________________________________________________________
(page generated 2024-10-13 22:02 UTC)