Hacker News Reader

Comment by simplyinfinity | Hacker News Reader

I just started using Hugo, but boy, are the docs bad... and I mean REAL BAD. It took me an HOUR to setup a theme. Then another 30 mins to realize I've set up the theme the wrong way, using a git submodule, instead of a go module. Then installation of the go module itself took another 30 mins of debugging, because nothing was working out of the box. And nowhere in the documentations are things explained for novices. The docs are written in a way that assumes you already know Hugo's ins and outs. uh... At this point, I would've been better off with a WordPress install that takes 5 minutes to do manually.

View on HN

Bep is rewriting the docs because are really incomprehensible. I do agree with you.

Four years ago Bep was rewriting the docs because they were incomprehensible (https://yawpitchroll.com/posts/hugo-probably-is-not-for-you/... last week I started looking again, and I wouldn’t say anything has improved, nor do I expect it to in 4 more.

Note to reader: the link is mangled up a little I think because of the closing parentheses? Here is a link without parentheses

https://yawpitchroll.com/posts/hugo-probably-is-not-for-you/

Had a similar experience, so I decided today to write a Github action[1] that automatically takes the contents of an Obsidian[2] vault, generates static content with Hugo and publishes it on Github pages. Hopefully I have documented the steps clearly [3].

After initial setup, the idea is you can edit a blog on any machine (not requiring Hugo locally). Just check out a repository, make changes and do a `git push`. All the hard work is done in a Github runner.

I wanted a simple way to be able to cut and paste screenshots into Markdown and generate a static site. Obsidian is both an excellent note taking tool and editor, so it seemed appropriate. Of course the markdown files can be edited with any editor.

[1] https://github.com/marketplace/actions/obsidian-to-hugo-page...

[2] https://obsidian.md/

[3] https://blog.x1sec.com/posts/obsidian-to-hugo-github-pages-a...

Is there a good alternative? Would be nice if it is in Python. Maybe Pelican, Nikola, Hyde?

Hugo is very opinionated. But that opinion it has isn't very well communicated, and I myself don't think I fully understand it enough to write docs on it.

Hugo has opinions on where files should be, how it should be transformed into pages. How those pages should be organized (ie: Taxonomies), and how users and template writers should be able to customize these elements to generate very different web pages.

------------

I do wonder if "Document Hugo" is the wrong approach, but instead the proper thing that needs to happen is "Create Beginner-Hugo-Template" and document that instead.

Then, "Create Intemediate-Hugo-Template" and document how various things you add to these Templates can improve a blog, or book, or various different webpage "ideas".

Hugo is great but the learning curve is madness. I've used it twice with a couple years in-between, and succeeded, but it's very annoying to have 1-3 hours of failure before you see anything useful.

Add theme, follow tutorial, somehow blows up, need to figure out exactly where to put what, round and round then find a tiny wedge that works and just expand that until I have something that does what I need. But once it's set up it's really fast and you can iterate on your pages very nicely. No "tons of imports" that I needed with Jekyll.

This past weekend I spent most of a day playing with various simple SSGs with the target of migrating my Hugo blog to something simpler. This was after I spent a couple hours in Hugo trying to generate a page with just simple links to all the blog posts.

My favorite was Hexo: Reasonably simple, default setup looked good. I wrote a larger (but still mini) review of Hexo, gostatic, and Zola: https://linsomniac.gitlab.io/post/2023-02-26-simple_static_s...

Years ago I rewrote our entire company website, including hundreds of blog posts an articles, as well as marketing stuff, in Pelican in a day or two.

When I set up my Hugo site originally, I think I spent some time munging around and eventually got it to work, but that was years ago and everything I learned is lost. So I need something dead simple. But not, unfortunately, so minimal as gostatic.

Cobalt is nice if you want simple: https://cobalt-org.github.io/

It's not python, but it is a single binary to be off and running.

Thanks for the pointer, I hadn't heard of that one. I'd put it in the same department as "gostatic" as being too minimal, unless you want to build the templates yourself. gostatic allowed me to have tags where from a quick look cobalt does not.

edit: Forgot to mention: The install option seems to be broken, you have to go into "Reference" to the install guide to find an alternative.

Hugo is really nice once you spend some time learning the templating system and how the variables get set up. It does have a learning curve at first, but I don't find any of the alternatives to be as compelling as hugo once you're up and running.

Lektor is Python based and Just Works, but it is far off the beaten track… https://www.getlektor.com/

I use and love Lektor! Built-in CMS, simple templating system, and a lot of flexibility if you want it (but with a great Quickstart option).

Even as a dummy Product Manager, I've been able to write two plugins[0] for it over the last couple weeks (I'm one of the many laid off folks with a wee bit of extra time), and it's been a joy. Definitely frustrating moments — the docs could be better — but the maintainers have been super kind and helpful. It'd definitely benefit from a larger, more active community. Join us!

[0] Shameless plug: just last night, I wrote about one of those plugins here: https://ft.io/blog/link-preview-images/

Nice work! Good write up.

I use Lektor for when I want extensibility, Zola when I want speed and won't ever need to create plugins.

WordPress. I hate its guts, but my god does it just work. Or I'm just going to give up and use squarespace or webflow, or something like that. I've got a full time job, managing this is not worth the mental energy it takes to learn all it's quirks.

I like Sphinx [0] with the MyST Markdown syntax [1]. There is a related project, Myst NB [2], which enables including Jupyter notebooks in your site. There is also a plugin for blogging [3].

[0]: https://www.sphinx-doc.org [1]: https://myst-parser.readthedocs.io [2]: https://myst-nb.readthedocs.io [3]: https://ablog.readthedocs.io

I found elevently the best of the bunch, as it deals with html and js so no need to spin up extra sdks or builds to get things going.

The docs aren't great either but didn't find them as cryptic as Hugo docs.

Astro is pretty awesome if you’re ok with TS/JS.

so its not just me --- amen i am not nuts

I've tried to use Hugo a few times, but quickly gave up after failing to figure out how to do the simplest things. Too bad, it seems very popular.

With Astro orwwq 11ty, I'm not sur or e why 9ooo up to it I>oop9 of ot33 just up 3eoo8 E3 w

Reply on news.ycombinator.com