23 ms·

Hugo is awesome, its documentation is not

258 points by KlatchianMist 5y ago

ListeningPie 5y ago
I gave up on the documentation and have been reading "Build Websites with Hugo" by Brain P Hogan. It's a step by step guide to a build website, and I find Hugo more approachable and understandable than React Static and Gatsby.
detaro 5y ago
While I agree with a lot of the points made, I feel like it overstates the need to "read so many pages". You don't need need to follow each link as soon as its presented, and reading just the discussed page does feel like it gives me a usable starting point, despite that I have never used Hugo, and not read any other documentation pages at this point.
- hombre_fatal 5y ago
  I know what they are talking about. A few years ago I tried using Hugo and it felt like the docs were made for people who already knew how it worked. After all, it's very hard to write docs from the eyes of someone who doesn't even know what the jargon is and why the various concepts exist. As a newcomer, you end up saying a lot of "okay, but what is a practical example of how this helps me?" as you scuttle through a bunch of browser tabs. At least back when I tried it, Hugo could use a guide like https://reactjs.org/tutorial/tutorial.html https://reactjs.org/tutorial/tutorial.html that builds up a website from the basics while incrementally using Hugo features to solve problems with a toy website like, say, e-shop product pages to show how things fit together.
CA0DA 5y ago
This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!
- ljm 5y ago
  The author could have saved a paragraph or two of preamble by choosing a less inflammatory title. No need to write a disclaimer about best intentions unless you chose language that could rile people up.
  - systemvoltage 5y ago
    How would you suggest to write a title that’s less inflammatory? I have a higher tolerance to this type of language. Some people find any critique offensive. Some embrace it. With any public confrontation, you’re bound to get a spectrum of people with various reactions. How do we make sure criticism, even harsh, needs space in public dialog whether it is open source or not? If it’s meant with good faith, that is. People these days have an adverse reaction to any sort of criticism and it is troubling. Anything other than a pat on the back and emojis is considered rude. We got rid of downvotes on YouTube and this was the justification.
    - autarch 5y ago
      Instead of "sucks", how about any of these: * My Frustrations with Hugo's Documentation * How Hugo's Documentation Confuses Me and How to Improve It * Why I Don't Like Hugo's Documentation The key thing I've done here in the first three is to reframe the criticism as an _opinion_ ("I", "me", "my") rather than an absolute ("it sucks"). I don't think it's too much to ask people to state their opinions _as opinions_ in cases where you know in advance that said opinion may lead to hurt feelings. These titles might _still_ lead to hurt feelings, but I think they're less likely to do so, and if they do then they will hurt less.
      - systemvoltage 5y ago
        Those are all great suggestions and that’s what I would use. However, if you look under the facade, when talking to your colleagues and with people around you, “sucks” is very much a common, daily word. This is the way I look at it. Sure, it’s not professional. But, the author is not trying to be professional I suppose. I am not going to debate it’s appropriateness. I want to be clear, the point I’m debating is not about “sucks” per se, but any general criticism. Whenever you need disclaimers, it could mean two things 1) Rude or unacceptable title 2) Society expects unreasonable conformity and adherence to a particular language, set of values, etc. In the case 2), we had a huge debate about “master vs main” branch. There are many examples. We’d be better off dialing down the conformity and be more inclusive. Check in deeper about intentions and faith, than the facade of language. If the author used the language you suggested, but had bad intentions, that’s a bigger problem.
StevenWaterman 5y ago
Thinking about the four kinds of documentation [1], it seems like the Hugo docs are structured as a reference but presented as an explanation/tutorial. I've found it useful to sit down and explicitly think about the purpose of a piece of documentation before writing it, and then write it with that purpose in mind. It sounds like a basic thing, but it's also the main reason people write bad documentation [1] https://documentation.divio.com/ https://documentation.divio.com/
- chatmasta 5y ago
  Love this system. BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/ https://diataxis.fr/
  - rsolva 5y ago
    Thank you for the link, this system really deserves its own dedicated website :)
- deleted 5y ago
  [deleted]
- aae42 5y ago
  > structured as a reference but presented as an explanation/tutorial i think you've hit on something here i read docs like this: https://gohugo.io/templates/lookup-order/ https://gohugo.io/templates/lookup-order/ which are incredibly useful, but i end up using it as a reference... hugo docs could use a run-through and re-org w/ the divio principles in mind
- _jal 5y ago
  Aside from the general lack of quality documentation these days, the decline of technical writing as a profession has been a big loss. They didn't just organize and write documentation. I recall doc interviews where tech writers would quiz me on how something worked, and on more than one occasion pointed out problems that sat at the intersection of functionality and UI that everyone else missed. And not my department, but I did get to see an amazing kerfluffle when an innocent question about an old feature everyone except the tech writers forgot about ended up derailing a release while people figured out how to reconcile things. Completely aside from function, really good technical documentation is just a joy to read and use. It is sad that "we" produce far less of it than we used to.
Kon-Peki 5y ago
It has been quite a while since I ran through some of their getting started stuff. My biggest problem with it is that if you don’t choose a theme the tutorials and guides don’t work. You didn’t get an un-themed vanilla site, you got a bunch of error messages and no HTML. Having a parallel set of tutorials that do not use a theme would make a large improvement in understanding what is going on.
dahdum 5y ago
There are so many ways to title the article and approach this topic, yet the author still chose a petulant and insulting one to vie for attention.
- unfocussed_mike 5y ago
  I think the title is silly, but the article is reasonable. I have this same problem with the documentation for the (really absolutely incredibly useful) Caddy webserver. Caddy itself is extremely powerful and you can do a lot with the configuration. But finding how you do that requires exploring the documentation as if it were a hypertext adventure. Some of this comes from the documentation effort being repeated for the significantly different 2.x version, but it's also a deliberate choice.
  - corobo 5y ago
    Caddy's 2.x documentation almost put me off Caddy haha Try to find how to use the `ask` function to verify whether a requested domain should get a certificate provisioned. If you can do it without having to manually sift through the docs and then give up and tackle it with trial and error I'll.. well I'll be put in my place, but it proper tripped me up when I needed it
    - unfocussed_mike 5y ago
      I had a bit of a battle to find out how to do a couple of things, but the weirdest challenge was to find out how to force it to refresh a Let's Encrypt certificate! I absolutely love the performance, and now I have it working, I am super-pleased with the simplicity of the configuration for e.g. a nuxt static site with a PHP graphql server. But it really was a bit mindbending.
vehemenz 5y ago
I can sympathize with the author. I once attempted Hugo and gave up after a few hours and proceeded with vanilla PHP, which for most contexts is better and easier than any static site generator.
PaulHoule 5y ago
It's a problem with most systems that introduce a number of new concepts, such as the documentation for the Spring framework. One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up. The worst thing about this situation is that people go look up wrong answers on programming splogs and StackOverflow and by the time you find a hugo that's been worked on for 3 years there is no rhyme or reason for how things are done because nobody has ever understood how hugo works and now you can't fix anything without risking massive breakage. I am going through this right now with a project that I may wind up doing with hugo. On one hand I can make the case that hugo is good for my case but I can also say that I'd be happier customizing a Python-based solution or that I think the markup in hugo is less than optimal (I guess I can do anything with shortcodes but I'd really like to do visualization and unique typography in some ways... I don't want to make something that looks like a second rate substack.) I haven't had the heart for a real battle against circularity by reading the documentation and with no definite deadline to get my hugo site up I find that other projects are tempting to think about instead...
- oauea 5y ago
  > One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up. I like opening such docs twice. The first to read through, and the second to search for more info about what I'm currently reading.
  - PaulHoule 5y ago
    That's a good idea. Sometimes you need to explore (build your understanding of the concepts behind the system) and sometimes you need to exploit (get the answer for one particular problem).
- andrelaszlo 5y ago
  I'm working a bit with GCP infrastructure lately and I find Google's docs very well-written, but suffering from a bit of the opposite problem. Many docs are written as how-tos for very specific scenarios, often the most basic setup thinkable (which makes sense!). If you're trying to understand the abstractions in order to see what will make sense for your own project, it's a difficult way to get the full picture. :D It seems like good docs often have two types of articles: 1. Short and clear definitions of terms, abstractions, resources, etc. 2. Self-contained how-tos and overview type articles on common issues and ways to use the product. If it's just one or the other, or both mixed up, I often find it frustrating.
jdubb 5y ago
Very recognizable. I've used Hugo for exactly one website, as a first introduction to static site generators. The site still runs, and if I need to change something running the `hugo` CLI still works. But it wasn't easy to get started, with all these new concepts, and this site explains clearly the trouble I had. Perhaps it's expected that when you use Hugo, you already recognize most concepts from other static site generators?
- evanelias 5y ago
  No, even with past static site generator experience, it can still be a struggle. I had extremely extensive experience with Movable Type, which was a once-hugely-popular blogging platform / CMS / static site generator. And by "extremely extensive", I mean I worked for the company that made the software, in their Services org which built Movable Type-driven sites for major media partners. Despite this, and also already having Golang html/template experience, Hugo's docs and concepts were still very difficult for me to learn!
  - chipotle_coyote 5y ago
    Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a directory of flat files and do testing, building and deployment from the command line. There's a few PHP-based systems out there that buck this trend, but they seem to mostly be commercial products pitched at small web design firms (e.g., Kirby, Statamic, Craft).
    - lolinder 5y ago
      One of the big reasons I lean toward static sites for my stuff is that you can host them out of an S3 bucket or similar with no dynamic endpoints whatsoever. This is a huge win for security for projects that I don't have time to keep constantly updating. A web-based admin backend largely eliminates that value unless it's run off a separate port that I can firewall, and even then I have to be sure I firewalled it correctly. There is a space that I'd like to explore, though, and that's having a static site generator that is built into a desktop-based GUI. My dream is to get the brain-dead security of an SSG without having to fiddle about with files and folder structures.
0xbadcafebee 5y ago
To the author: I love that you use different formatting to break up your page, but I also recommend breaking up some of your paragraphs, as they are a little dense.
atishay811 5y ago
Hugo’s documentation is a great reference and very well articulated. If you are looking for a tutorial and want to grow understanding, a book might be much better. I am the author of Hugo In Action (https://hugoinaction.com https://hugoinaction.com) and the objective of my book is to introduce the concepts slowly and with a running example for easily trying out.
- svnpenn 5y ago
  > Hugo’s documentation is a great reference and very well articulated No its not, and not its not. Hugo it easy to install and/or build, I will give it that. But the documentation has always been poor in my mind, with gaping holes for common uses that are maybe outside of the opinionated "norms".
  - wink 5y ago
    It's been a while, but I'd sum it up as: I want to do A, B, C. Now I need to find out how A,B,C are called in hugo, how they relate to each other, which mandatory concepts D,E they depend on, how those relate to each other and then, if everything would be perfectly written, I might understand it. I actually think it's a good reference. If you know what an archetype is and what you can do with it, just forgot the syntax? Bingo. To grasp what its good for? Not so much. Maybe if someone collected a bunch of actual problems of "How do I ...?" and made them into a really good FAQ, that might help? That said, I also don't have a solution - I think they've succumbed to feature creep a little too much. In the quest to let every non-programmer be able to tweak every single thing, now the non-programmer needs to learn a DSL.
andrelaszlo 5y ago
One good way to understand how something works is to write documentation for it. In this case it seems like the author has pretty strong opinions about how it should be done. It's a big job, of course, but perhaps similar in effort to writing a blog post? I don't mean to be snarky! Just got the feeling that the current docs are written a bit as an afterthought and that the blogger, on the other hand, is a good writer. I wonder how useful this type of feedback is, and if the irritation over the docs could have been challenged into something more impactful.
- digianarchist 5y ago
  I think the post serves as general advice for writing documentation for a project. If the author had gone off and wrote docs for Hugo they 1. Might not have been accepted 2. Wouldn't contain info on why the docs are bad.
adriangrigore 5y ago
Feedback on my static site generator's documentation if we're here? :D https://mkws.sh/docs.html https://mkws.sh/docs.html
- svnpenn 5y ago
  > using sh as a templating language. You should probably explain what "sh" is. It may seem obvious to you, but not to everyone. Something like: > using POSIX shell "sh" as a templating language. (hopefully youre using POSIX?). Also, where is the source code? I see this: https://mkws.sh/mkws@4.0.16.tgz https://mkws.sh/mkws@4.0.16.tgz but do you really not use version control?
  - adriangrigore 5y ago
    Not sure if people who understand > POSIX Shell "sh" don't understand > sh Thanks for the suggestion! Yes, it's certainly POSIX, I don't use version control now, I run a back up cron every 30 minutes. Playing around without git. Sources: https://mkws.sh/docs.html#sources https://mkws.sh/docs.html#sources
    - svnpenn 5y ago
      Where are the previous versions?
      - adriangrigore 5y ago
        They're not listed, good idea to list them somewhere.
thrower123 5y ago
There's never been a CMS system that doesn't suck in this exact way. It's the nature of the beast.
- throwawayboise 5y ago
  Yes, it gets back to essential complexity vs. accidental complexity, like most software that does anything non-trivial.
chrisbrandow 5y ago
As someone who is a competent iOS developer but not much of a web developer, all I can say is that I completely identify with this critique. The Hugo docs are just straight to the deep end.
- subpixel 5y ago
  As someone who is(was?) a competent web developer, all I can say is that Hugo templating turned me off of the project. For as long as I used Hugo, I felt like I was in a horror corn maze.
- zellyn 5y ago
  As someone who is an experienced back-end developer, and used Hugo quite early on, and has understood enough of the Hugo/Goldmark integration to write and install a custom markdown plugin, all I can say is that I _completely identify_ with this critique. I would add: - the ecosystem of Hugo theme production/rating seems SEO-scammy - the docs seem uncertain on whether you should use “Modules” That said, I was able to hack pikchr.org support into my blog, and the ability to create beautiful diagrams[1] while previewing with live refresh has been amazing. [1] eg: https://zellyn.com/2022/02/cs-ramble/1c/ https://zellyn.com/2022/02/cs-ramble/1c/
ivanech 5y ago
When I made my site statically generated, I considered using Hugo, but I ruled it out after 15 or so minutes because i ran into the same issue with the docs. Ended up just writing a python script to do it which didn't take long
- bigpeopleareold 5y ago
  The only thing I did different is spent more than 15 minutes on trying to understand the documentation. Maybe it was just finding what the secret was that deserved such dense documentation.
austinpena 5y ago
I really dislike that I had to, but I migrated to Next JS for the sole sake of the IDE support that comes with JSX. It's super convenient to have autocomplete, syntax highlighting and everything that comes with it. If Hugo could have that too, I'd go for it in a second.
deleted 5y ago
[deleted]
alleycat5000 5y ago
I've also found Hugo's docs hard to use, but had a great experience learning it from https://pragprog.com/titles/bhhugo/build-websites-with-hugo/ https://pragprog.com/titles/bhhugo/build-websites-with-hugo/
- bphogan 5y ago
  Hey, author here. Thanks so much for the kind words! I love Hugo, and I wanted to give people a real-world tour of how to build something concrete with it.
- rsolva 5y ago
  This goes to show that Hugo is quite excellent, but it's docs are lacking. Learning it was one long fight, but after having understood the basic concepts and gained experience using it for several projects, I really came to appreciate this static site generator.
say_it_as_it_is 5y ago
Rather than contribute to improving the documentation, why not spend hours creating a web site and blog post flaming about the problem instead?
rsolva 5y ago
This quote from the conclusion sums up my personal experience with Hugos docs: > The thing is, after having spent a lot of time tinkering with Hugo, I have now assimilated enough knowledge that the existing Hugo docs make perfect sense…most of the time. Maybe this is the case with other users of Hugo too. However, I still remember how frustrating it felt while reading the docs for the first time.
throwaway284534 5y ago
My most frustrating experience with Hugo is their template language and lack of clear explanations, often waiving away any complexities as, “They’re just Go templates.” Fair enough, but the docs make no attempt to explain how scoping works, how variables can be applied to partials, or even how to construct a simple for-loop. There’s an answer for each of these problems but implementing a full solution requires scouring through the Go docs and Hugo’s own forums for a complete and pragmatic solution. I had a heck of a time with Hugo’s concept of “Scratch” while generating a breadcrumb navigation. Combined with a JSON schema, Google will include these crumb segments in search results. But much like Handlebars, Go template expressions aren’t REPL friendly, and a the learning experience involves a lot of refreshing and debug output just to get a clue as to how things work. Personally, this has bitten me with every “stringly” typed template language. IDE’s have little information to work with, and much like playing a game of Wordle, you’re left to fill in the blanks — one line at a time.
- bborud 5y ago
  If something is a pain in the ass to document, it is probably not very clear. Hugo has a bit too much implicit magic that feels unnecessary. It wouldn't have killed us users if things were a bit more explicit. Every time I restructure how I do my personal website I get a strong urge to sit down and write a more disciplined static website generator. (Don't worry. I won't. I don't have that kind of spare time on my hands). Obviously one that has fewer degrees of freedom so as to make theming meaningfully possible. Because Hugo themes aren't really themes. They are more like applications where your website probably isn't going to work without a lot of hacking.
- rr808 5y ago
  I've had the same issue with Helm Templates - "they're just Go templates".
- regus 5y ago
  I agree with you completely about the templates. When I first used Hugo I was not well versed in Go, nor did I have any idea how it's templating system worked. Reading the docs lead me to believe that the templates were invented by Hugo. It would of been helpful to make the distinction because I could have looked up how the templates work. I'm not sure if it would have helped though because Go's templates are incredibly confusing and frustrating to use.
karaterobot 5y ago
I remember making the case to spend a few days to testing out Hugo as an alternative to Jekyll for our company's website. At that time, about 3 years go, I bounced off this documentation pretty hard as well. It does not appear to have improved significantly, which is a shame. On the other hand, I now know that, in cases like this, you'd go watch some video tutorials before going back to the documentation armed with enough conceptual knowledge to maybe prime the pump and make that cryptic documentation start to fall into place (lots of mixed metaphors there). You shouldn't have to, but it's nice that there's the option.
bojanvidanovic 5y ago
From my personal experience, confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything. Some time ago, I made a very simple blog (https://devandgear.com https://devandgear.com) in Hugo, which eventually with time evolved into a much bigger and more complex website (>2000 pages), that evolvement was possible thanks to its wide array of tools otherwise it would require a different builder.
- nouveaux 5y ago
  > confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything I have not used Hugo and I have no idea how powerful it is but I am quite skeptical. It's hard for me to believe that it is more powerful and flexible than Django and Django's documentation is very good.
azangru 5y ago
As a web developer, primarily on the front end, all I can say these days is: Eleventy.
- qbasic_forever 5y ago
  Yeah, I wish there were a go version of the same minimal template engine/swiss army knife that is eleventy. Hugo is nice if you need some full fledged CMS workflow and can do everything the hugo way. But IMHO if you're just turning some markdown into HTML with a simple template then hugo has far too many concepts and abstractions. Eleventy is a breath of fresh air and can be learned and made productive in an afternoon.
jerf 5y ago
I recently started using Hugo for a few websites. I endorse this. To give a concrete example, I spent quite a while just figuring out what it means to put a piece of content into a directory under hugo, and I still don't have a full grasp on it, honestly. What does it mean to put something under "content/posts/2011" versus dumping it into content/posts? How exactly do categories and tags get populated? (What is the difference between them?) Something as basic as that has taken me quite a while to get through. (Please note I am not asking for answers to those questions here. In fact dumping the answers here in a nice, clean, easy-to-understand format that walks you through from start to finish would be in some sense actively counterproductive. Go dump them in the Hugo docs!) I can not point you at a specific page that describes the answer to this question. I can not point you at a specific page that describes how we get from content to the various collections of content. This documentation exists, but it's buried in a generic listing that has tons of other stuff, and IIRC still doesn't describe edge cases; I was experimenting with things just to see what they did, because I don't think the docs even acknowledged the edge case. Also, there's a lot of stuff made available in the templates but there's nothing like type-level documentation that says what is of what type and what that type can do; collections of pages will be described almost literally as that, but with no link to exactly what a Page object is. Again, it's probably all there somewhere but it's very hard to use. I mean, technically it's all there, but I certainly had to go on an adventure to get it all. The tutorial also suffers from being too simplified. Tutorials always have this temptation to show off all the magic being used in its simplest possible default configuration, which is fine, but then if you want something other that the simplest possible default configuration you're left with not much to go on. It could be worse, but it certainly has some organizational problems. No matter what problem I come the documentation with, be it looking up what an API does, trying to understand a subsystem, understanding the whole thing holistically, figuring out why I want a certain feature (I almost manually recreated the entire concept of a manual taxonomy before figuring out what it actually meant), the docs just never quite manage to answer my question.
kvnnews 5y ago
I used Hugo for a while and remember their documentation and ultimately the implementation itself was confusing, which then resulted in an overly complex data structure that was hard to modify. Also tried a few other static site generators before just writing my own with python+markdown+jinja+etc.
awill 5y ago
I've been using Hugo for several years. But I'm mostly using freely available templates with minimal changes. Though some of those changes do require a lot of trial and error due to the lacking documentation. Is the competition better? I see a lot of buzz around eleventy. There's also Pelican, Jekyll, Gatsby and many others.
eloff 5y ago
I like Hugo quite a lot, but I don't like Go's standard library templates. I wonder if it is possible to use https://github.com/valyala/quicktemplate https://github.com/valyala/quicktemplate with Hugo?
- sreevisakh 5y ago
  Zola [1] was created exactly for this reason. It even says so in the Readme. The templates are based on Jinja though, not mako. They also claim that their CLI is intuitive and documentation is good. I certainly found it more comprehensible than Hugo's. [1] https://www.getzola.org/ https://www.getzola.org/
  - rimutaka 5y ago
    I switched from Hugo to Zola. Happy as Larry.
  - eloff 5y ago
    Nice, thanks for the link, it looks interesting. Implemented in Rust.
cryptos 5y ago
The template engine is not so awesome (it is the Go template engine, really awkward!). Another thing that is really not awesome is that Hugo doesn't use semantic versioning, so that you don't have any idea whether the new version will break your project or not.
- yoz-y 5y ago
  Once a Hugo update broke my website. So what I did was to take the latest version of the binary, and chugged it in the repo with the site code. Now I just never update. Also helps with the urge to tweak things instead of writing (not that I write much anyways).
quyleanh 5y ago
And so does its themes. It seems that the good UI/UX web designers don't have interest to Hugo theme. I check the Hugo theme site [0], but difficult to find out the good one. Not like some React/Vue community. Here is my wife site [1] with custom Call me Sam theme [2]. Check it out and let see what a hardware designer can do for his wife :) [0] https://themes.gohugo.io/ https://themes.gohugo.io/ [1] https://imblien.com/ https://imblien.com/ [2]https://github.com/victoriadrake/hugo-theme-sam https://github.com/victoriadrake/hugo-theme-sam
vanisher93 5y ago
I mean, I get it, but why not opening a couple of PRs then? It is an open source project after all.
byteski 5y ago
well I figured out how Hugo works only by “clone the existing Hugo theme, change something, see what happens”.
WaitWaitWha 5y ago
I believe we also discussed Hugo here: https://news.ycombinator.com/item?id=30142558 https://news.ycombinator.com/item?id=30142558
dkarl 5y ago
As another poster said, the problem is that Hugo is built around a number of new concepts. To understand them, you have to understand their relation to two contexts: the other Hugo concepts that they are designed to work with, and Hugo's purpose of generating web sites from data. The docs are written almost entirely in the first context, building the concepts up and explaining how they work together, so if you start with the docs you can end up spending a lot of time trying to create a mental model entirely out of these concepts, with no connection to the concrete function of the software.
hugopipes 5y ago
I
hugopipes 5y ago
It is too big of an ask to ask a beginner to make a pull request, let alone contribute to Hugo Docs! I have raised close to three issues in the forum about the docs and how straightforward the issues I raised could be made but I was overruled by the mods.
earthboundkid 5y ago
I've made a lot of sites with Hugo, and so I appreciate the Hugo docs as a reference, but I agree that they're not suitable as a tutorial for new users.
recursive 5y ago
Hugo documentation is a monad tutorial.
jordanmorgan10 5y ago
For this precise reason, I use Jekyll. I got so frustrated with Hugo, and when I went to Jekyll they had an entire "From start to finish, make a blog with Jekyll" in their docs. That made all of the difference for me. This was about 3 years ago, so maybe things have changed. But last time I checked, Jekyll still had that guide up.
shadowgovt 5y ago
I've found one of the recommended books very useful for getting started (https://www.manning.com/books/hugo-in-action https://www.manning.com/books/hugo-in-action). But, (a) it's preprint and has copy-editing bugs and (b) it doesn't address the issue of the lack of reference docs.
fmajid 5y ago
It's not ideal, but it is comprehensive. Infinitely superior to the Wordpress or Joomla documentation. It helps the system is less baroque to begin with.
amai 5y ago
Hugo would be a lot more awesome, if they would fix this 7 year old issue : Add ability to generate per-{year, month, day} archives: https://github.com/gohugoio/hugo/issues/448 https://github.com/gohugoio/hugo/issues/448
synergy20 5y ago
I now think rust-based mdbook is simpler and better than hugo, give it a spin. the limit of mdbook is that it's one book only. another one is vitepress(vue3 based but you don't need know vue3 to use vitepress) that you can have multiple 'books' under one site.
throwaway5486nv 5y ago
How could some framework be awesome without having good documentation?
sandreas 5y ago
I pretty much had the same experience. If someone is interested in my personal notes how to get started from scratch with hugo, see https://pilabor.com/blog/2021/05/building-a-blog-with-hugo/ https://pilabor.com/blog/2021/05/building-a-blog-with-hugo/
stonecharioteer 5y ago
I tried Hugo, and Jekyll and my biggest gripe with either is the Markdown format. I prefer RestructuredText and it is truly a superior format. I understand why Markdown is more popular but I can't understand why these static site generators support only Markdown. Sphinx supports both, and I use it everywhere. Paired with Pradyun's Furo theme, it truly is a far better experience.
mbrodersen 5y ago
Writing good documentation is exactly like writing good software: you need to start with a known foundation (the readers prior knowledge/the OS platform) and then build layers of knowledge/software on top of that. One layer at a time. And never have circular dependencies. This is why I recommend only hiring software developers who communicate clearly. Software developers who can’t communicate clearly will write software that is badly structured and hard to maintain. A confused/unclear/unsystematic mind will write confusing/unclear/unsystematic documentation/software.
zwbetz 5y ago
I'm a big hugo fan. I contribute to their forum. I use hugo to build my site. I've used it on freelance projects. I could go on and on about it. I do hear the concerns here. I agree that the docs are more reference style, and less tutorial style. (Tho, as you gain experience, you prefer the reference style). After I learned hugo, I wrote the tutorial I wish I would of had. Am shamelessly sharing it here in case it's useful for someone else wanting to deep dive: https://zwbetz.com/make-a-hugo-blog-from-scratch/ https://zwbetz.com/make-a-hugo-blog-from-scratch/

258 points by KlatchianMist 5y ago

I gave up on the documentation and have been reading "Build Websites with Hugo" by Brain P Hogan. It's a step by step guide to a build website, and I find Hugo more approachable and understandable than React Static and Gatsby.

detaro 5y ago

While I agree with a lot of the points made, I feel like it overstates the need to "read so many pages". You don't need need to follow each link as soon as its presented, and reading just the discussed page does feel like it gives me a usable starting point, despite that I have never used Hugo, and not read any other documentation pages at this point.

hombre_fatal 5y ago
I know what they are talking about. A few years ago I tried using Hugo and it felt like the docs were made for people who already knew how it worked. After all, it's very hard to write docs from the eyes of someone who doesn't even know what the jargon is and why the various concepts exist. As a newcomer, you end up saying a lot of "okay, but what is a practical example of how this helps me?" as you scuttle through a bunch of browser tabs. At least back when I tried it, Hugo could use a guide like https://reactjs.org/tutorial/tutorial.html https://reactjs.org/tutorial/tutorial.html that builds up a website from the basics while incrementally using Hugo features to solve problems with a toy website like, say, e-shop product pages to show how things fit together.

CA0DA 5y ago

This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!

ljm 5y ago
The author could have saved a paragraph or two of preamble by choosing a less inflammatory title. No need to write a disclaimer about best intentions unless you chose language that could rile people up.
- systemvoltage 5y ago
  How would you suggest to write a title that’s less inflammatory? I have a higher tolerance to this type of language. Some people find any critique offensive. Some embrace it. With any public confrontation, you’re bound to get a spectrum of people with various reactions. How do we make sure criticism, even harsh, needs space in public dialog whether it is open source or not? If it’s meant with good faith, that is. People these days have an adverse reaction to any sort of criticism and it is troubling. Anything other than a pat on the back and emojis is considered rude. We got rid of downvotes on YouTube and this was the justification.
  - autarch 5y ago
    Instead of "sucks", how about any of these: * My Frustrations with Hugo's Documentation * How Hugo's Documentation Confuses Me and How to Improve It * Why I Don't Like Hugo's Documentation The key thing I've done here in the first three is to reframe the criticism as an _opinion_ ("I", "me", "my") rather than an absolute ("it sucks"). I don't think it's too much to ask people to state their opinions _as opinions_ in cases where you know in advance that said opinion may lead to hurt feelings. These titles might _still_ lead to hurt feelings, but I think they're less likely to do so, and if they do then they will hurt less.
    - systemvoltage 5y ago
      Those are all great suggestions and that’s what I would use. However, if you look under the facade, when talking to your colleagues and with people around you, “sucks” is very much a common, daily word. This is the way I look at it. Sure, it’s not professional. But, the author is not trying to be professional I suppose. I am not going to debate it’s appropriateness. I want to be clear, the point I’m debating is not about “sucks” per se, but any general criticism. Whenever you need disclaimers, it could mean two things 1) Rude or unacceptable title 2) Society expects unreasonable conformity and adherence to a particular language, set of values, etc. In the case 2), we had a huge debate about “master vs main” branch. There are many examples. We’d be better off dialing down the conformity and be more inclusive. Check in deeper about intentions and faith, than the facade of language. If the author used the language you suggested, but had bad intentions, that’s a bigger problem.

StevenWaterman 5y ago

Thinking about the four kinds of documentation [1], it seems like the Hugo docs are structured as a reference but presented as an explanation/tutorial. I've found it useful to sit down and explicitly think about the purpose of a piece of documentation before writing it, and then write it with that purpose in mind. It sounds like a basic thing, but it's also the main reason people write bad documentation [1] https://documentation.divio.com/ https://documentation.divio.com/

chatmasta 5y ago
Love this system. BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/ https://diataxis.fr/
- rsolva 5y ago
  Thank you for the link, this system really deserves its own dedicated website :)
deleted 5y ago
[deleted]
aae42 5y ago
> structured as a reference but presented as an explanation/tutorial i think you've hit on something here i read docs like this: https://gohugo.io/templates/lookup-order/ https://gohugo.io/templates/lookup-order/ which are incredibly useful, but i end up using it as a reference... hugo docs could use a run-through and re-org w/ the divio principles in mind
_jal 5y ago
Aside from the general lack of quality documentation these days, the decline of technical writing as a profession has been a big loss. They didn't just organize and write documentation. I recall doc interviews where tech writers would quiz me on how something worked, and on more than one occasion pointed out problems that sat at the intersection of functionality and UI that everyone else missed. And not my department, but I did get to see an amazing kerfluffle when an innocent question about an old feature everyone except the tech writers forgot about ended up derailing a release while people figured out how to reconcile things. Completely aside from function, really good technical documentation is just a joy to read and use. It is sad that "we" produce far less of it than we used to.

Kon-Peki 5y ago

It has been quite a while since I ran through some of their getting started stuff. My biggest problem with it is that if you don’t choose a theme the tutorials and guides don’t work. You didn’t get an un-themed vanilla site, you got a bunch of error messages and no HTML. Having a parallel set of tutorials that do not use a theme would make a large improvement in understanding what is going on.

dahdum 5y ago

There are so many ways to title the article and approach this topic, yet the author still chose a petulant and insulting one to vie for attention.

unfocussed_mike 5y ago
I think the title is silly, but the article is reasonable. I have this same problem with the documentation for the (really absolutely incredibly useful) Caddy webserver. Caddy itself is extremely powerful and you can do a lot with the configuration. But finding how you do that requires exploring the documentation as if it were a hypertext adventure. Some of this comes from the documentation effort being repeated for the significantly different 2.x version, but it's also a deliberate choice.
- corobo 5y ago
  Caddy's 2.x documentation almost put me off Caddy haha Try to find how to use the `ask` function to verify whether a requested domain should get a certificate provisioned. If you can do it without having to manually sift through the docs and then give up and tackle it with trial and error I'll.. well I'll be put in my place, but it proper tripped me up when I needed it
  - unfocussed_mike 5y ago
    I had a bit of a battle to find out how to do a couple of things, but the weirdest challenge was to find out how to force it to refresh a Let's Encrypt certificate! I absolutely love the performance, and now I have it working, I am super-pleased with the simplicity of the configuration for e.g. a nuxt static site with a PHP graphql server. But it really was a bit mindbending.

vehemenz 5y ago

I can sympathize with the author. I once attempted Hugo and gave up after a few hours and proceeded with vanilla PHP, which for most contexts is better and easier than any static site generator.

PaulHoule 5y ago

It's a problem with most systems that introduce a number of new concepts, such as the documentation for the Spring framework. One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up. The worst thing about this situation is that people go look up wrong answers on programming splogs and StackOverflow and by the time you find a hugo that's been worked on for 3 years there is no rhyme or reason for how things are done because nobody has ever understood how hugo works and now you can't fix anything without risking massive breakage. I am going through this right now with a project that I may wind up doing with hugo. On one hand I can make the case that hugo is good for my case but I can also say that I'd be happier customizing a Python-based solution or that I think the markup in hugo is less than optimal (I guess I can do anything with shortcodes but I'd really like to do visualization and unique typography in some ways... I don't want to make something that looks like a second rate substack.) I haven't had the heart for a real battle against circularity by reading the documentation and with no definite deadline to get my hugo site up I find that other projects are tempting to think about instead...

oauea 5y ago
> One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up. I like opening such docs twice. The first to read through, and the second to search for more info about what I'm currently reading.
- PaulHoule 5y ago
  That's a good idea. Sometimes you need to explore (build your understanding of the concepts behind the system) and sometimes you need to exploit (get the answer for one particular problem).
andrelaszlo 5y ago
I'm working a bit with GCP infrastructure lately and I find Google's docs very well-written, but suffering from a bit of the opposite problem. Many docs are written as how-tos for very specific scenarios, often the most basic setup thinkable (which makes sense!). If you're trying to understand the abstractions in order to see what will make sense for your own project, it's a difficult way to get the full picture. :D It seems like good docs often have two types of articles: 1. Short and clear definitions of terms, abstractions, resources, etc. 2. Self-contained how-tos and overview type articles on common issues and ways to use the product. If it's just one or the other, or both mixed up, I often find it frustrating.

jdubb 5y ago

Very recognizable. I've used Hugo for exactly one website, as a first introduction to static site generators. The site still runs, and if I need to change something running the `hugo` CLI still works. But it wasn't easy to get started, with all these new concepts, and this site explains clearly the trouble I had. Perhaps it's expected that when you use Hugo, you already recognize most concepts from other static site generators?

evanelias 5y ago
No, even with past static site generator experience, it can still be a struggle. I had extremely extensive experience with Movable Type, which was a once-hugely-popular blogging platform / CMS / static site generator. And by "extremely extensive", I mean I worked for the company that made the software, in their Services org which built Movable Type-driven sites for major media partners. Despite this, and also already having Golang html/template experience, Hugo's docs and concepts were still very difficult for me to learn!
- chipotle_coyote 5y ago
  Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a directory of flat files and do testing, building and deployment from the command line. There's a few PHP-based systems out there that buck this trend, but they seem to mostly be commercial products pitched at small web design firms (e.g., Kirby, Statamic, Craft).
  - lolinder 5y ago
    One of the big reasons I lean toward static sites for my stuff is that you can host them out of an S3 bucket or similar with no dynamic endpoints whatsoever. This is a huge win for security for projects that I don't have time to keep constantly updating. A web-based admin backend largely eliminates that value unless it's run off a separate port that I can firewall, and even then I have to be sure I firewalled it correctly. There is a space that I'd like to explore, though, and that's having a static site generator that is built into a desktop-based GUI. My dream is to get the brain-dead security of an SSG without having to fiddle about with files and folder structures.

0xbadcafebee 5y ago

To the author: I love that you use different formatting to break up your page, but I also recommend breaking up some of your paragraphs, as they are a little dense.

atishay811 5y ago

Hugo’s documentation is a great reference and very well articulated. If you are looking for a tutorial and want to grow understanding, a book might be much better. I am the author of Hugo In Action (https://hugoinaction.com https://hugoinaction.com) and the objective of my book is to introduce the concepts slowly and with a running example for easily trying out.

svnpenn 5y ago
> Hugo’s documentation is a great reference and very well articulated No its not, and not its not. Hugo it easy to install and/or build, I will give it that. But the documentation has always been poor in my mind, with gaping holes for common uses that are maybe outside of the opinionated "norms".
- wink 5y ago
  It's been a while, but I'd sum it up as: I want to do A, B, C. Now I need to find out how A,B,C are called in hugo, how they relate to each other, which mandatory concepts D,E they depend on, how those relate to each other and then, if everything would be perfectly written, I might understand it. I actually think it's a good reference. If you know what an archetype is and what you can do with it, just forgot the syntax? Bingo. To grasp what its good for? Not so much. Maybe if someone collected a bunch of actual problems of "How do I ...?" and made them into a really good FAQ, that might help? That said, I also don't have a solution - I think they've succumbed to feature creep a little too much. In the quest to let every non-programmer be able to tweak every single thing, now the non-programmer needs to learn a DSL.

andrelaszlo 5y ago

One good way to understand how something works is to write documentation for it. In this case it seems like the author has pretty strong opinions about how it should be done. It's a big job, of course, but perhaps similar in effort to writing a blog post? I don't mean to be snarky! Just got the feeling that the current docs are written a bit as an afterthought and that the blogger, on the other hand, is a good writer. I wonder how useful this type of feedback is, and if the irritation over the docs could have been challenged into something more impactful.

digianarchist 5y ago
I think the post serves as general advice for writing documentation for a project. If the author had gone off and wrote docs for Hugo they 1. Might not have been accepted 2. Wouldn't contain info on why the docs are bad.

adriangrigore 5y ago

Feedback on my static site generator's documentation if we're here? :D https://mkws.sh/docs.html https://mkws.sh/docs.html

svnpenn 5y ago
> using sh as a templating language. You should probably explain what "sh" is. It may seem obvious to you, but not to everyone. Something like: > using POSIX shell "sh" as a templating language. (hopefully youre using POSIX?). Also, where is the source code? I see this: https://mkws.sh/mkws@4.0.16.tgz https://mkws.sh/mkws@4.0.16.tgz but do you really not use version control?
- adriangrigore 5y ago
  Not sure if people who understand > POSIX Shell "sh" don't understand > sh Thanks for the suggestion! Yes, it's certainly POSIX, I don't use version control now, I run a back up cron every 30 minutes. Playing around without git. Sources: https://mkws.sh/docs.html#sources https://mkws.sh/docs.html#sources
  - svnpenn 5y ago
    Where are the previous versions?
    - adriangrigore 5y ago
      They're not listed, good idea to list them somewhere.

thrower123 5y ago

There's never been a CMS system that doesn't suck in this exact way. It's the nature of the beast.

throwawayboise 5y ago
Yes, it gets back to essential complexity vs. accidental complexity, like most software that does anything non-trivial.

chrisbrandow 5y ago

As someone who is a competent iOS developer but not much of a web developer, all I can say is that I completely identify with this critique. The Hugo docs are just straight to the deep end.

subpixel 5y ago
As someone who is(was?) a competent web developer, all I can say is that Hugo templating turned me off of the project. For as long as I used Hugo, I felt like I was in a horror corn maze.
zellyn 5y ago
As someone who is an experienced back-end developer, and used Hugo quite early on, and has understood enough of the Hugo/Goldmark integration to write and install a custom markdown plugin, all I can say is that I _completely identify_ with this critique. I would add: - the ecosystem of Hugo theme production/rating seems SEO-scammy - the docs seem uncertain on whether you should use “Modules” That said, I was able to hack pikchr.org support into my blog, and the ability to create beautiful diagrams[1] while previewing with live refresh has been amazing. [1] eg: https://zellyn.com/2022/02/cs-ramble/1c/ https://zellyn.com/2022/02/cs-ramble/1c/

ivanech 5y ago

When I made my site statically generated, I considered using Hugo, but I ruled it out after 15 or so minutes because i ran into the same issue with the docs. Ended up just writing a python script to do it which didn't take long

bigpeopleareold 5y ago
The only thing I did different is spent more than 15 minutes on trying to understand the documentation. Maybe it was just finding what the secret was that deserved such dense documentation.

austinpena 5y ago

I really dislike that I had to, but I migrated to Next JS for the sole sake of the IDE support that comes with JSX. It's super convenient to have autocomplete, syntax highlighting and everything that comes with it. If Hugo could have that too, I'd go for it in a second.

deleted 5y ago

[deleted]

alleycat5000 5y ago

I've also found Hugo's docs hard to use, but had a great experience learning it from https://pragprog.com/titles/bhhugo/build-websites-with-hugo/ https://pragprog.com/titles/bhhugo/build-websites-with-hugo/

bphogan 5y ago
Hey, author here. Thanks so much for the kind words! I love Hugo, and I wanted to give people a real-world tour of how to build something concrete with it.
rsolva 5y ago
This goes to show that Hugo is quite excellent, but it's docs are lacking. Learning it was one long fight, but after having understood the basic concepts and gained experience using it for several projects, I really came to appreciate this static site generator.

say_it_as_it_is 5y ago

Rather than contribute to improving the documentation, why not spend hours creating a web site and blog post flaming about the problem instead?

rsolva 5y ago

This quote from the conclusion sums up my personal experience with Hugos docs: > The thing is, after having spent a lot of time tinkering with Hugo, I have now assimilated enough knowledge that the existing Hugo docs make perfect sense…most of the time. Maybe this is the case with other users of Hugo too. However, I still remember how frustrating it felt while reading the docs for the first time.

throwaway284534 5y ago

My most frustrating experience with Hugo is their template language and lack of clear explanations, often waiving away any complexities as, “They’re just Go templates.” Fair enough, but the docs make no attempt to explain how scoping works, how variables can be applied to partials, or even how to construct a simple for-loop. There’s an answer for each of these problems but implementing a full solution requires scouring through the Go docs and Hugo’s own forums for a complete and pragmatic solution. I had a heck of a time with Hugo’s concept of “Scratch” while generating a breadcrumb navigation. Combined with a JSON schema, Google will include these crumb segments in search results. But much like Handlebars, Go template expressions aren’t REPL friendly, and a the learning experience involves a lot of refreshing and debug output just to get a clue as to how things work. Personally, this has bitten me with every “stringly” typed template language. IDE’s have little information to work with, and much like playing a game of Wordle, you’re left to fill in the blanks — one line at a time.

bborud 5y ago
If something is a pain in the ass to document, it is probably not very clear. Hugo has a bit too much implicit magic that feels unnecessary. It wouldn't have killed us users if things were a bit more explicit. Every time I restructure how I do my personal website I get a strong urge to sit down and write a more disciplined static website generator. (Don't worry. I won't. I don't have that kind of spare time on my hands). Obviously one that has fewer degrees of freedom so as to make theming meaningfully possible. Because Hugo themes aren't really themes. They are more like applications where your website probably isn't going to work without a lot of hacking.
rr808 5y ago
I've had the same issue with Helm Templates - "they're just Go templates".
regus 5y ago
I agree with you completely about the templates. When I first used Hugo I was not well versed in Go, nor did I have any idea how it's templating system worked. Reading the docs lead me to believe that the templates were invented by Hugo. It would of been helpful to make the distinction because I could have looked up how the templates work. I'm not sure if it would have helped though because Go's templates are incredibly confusing and frustrating to use.

karaterobot 5y ago

I remember making the case to spend a few days to testing out Hugo as an alternative to Jekyll for our company's website. At that time, about 3 years go, I bounced off this documentation pretty hard as well. It does not appear to have improved significantly, which is a shame. On the other hand, I now know that, in cases like this, you'd go watch some video tutorials before going back to the documentation armed with enough conceptual knowledge to maybe prime the pump and make that cryptic documentation start to fall into place (lots of mixed metaphors there). You shouldn't have to, but it's nice that there's the option.

bojanvidanovic 5y ago

From my personal experience, confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything. Some time ago, I made a very simple blog (https://devandgear.com https://devandgear.com) in Hugo, which eventually with time evolved into a much bigger and more complex website (>2000 pages), that evolvement was possible thanks to its wide array of tools otherwise it would require a different builder.

nouveaux 5y ago
> confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything I have not used Hugo and I have no idea how powerful it is but I am quite skeptical. It's hard for me to believe that it is more powerful and flexible than Django and Django's documentation is very good.

azangru 5y ago

As a web developer, primarily on the front end, all I can say these days is: Eleventy.

qbasic_forever 5y ago
Yeah, I wish there were a go version of the same minimal template engine/swiss army knife that is eleventy. Hugo is nice if you need some full fledged CMS workflow and can do everything the hugo way. But IMHO if you're just turning some markdown into HTML with a simple template then hugo has far too many concepts and abstractions. Eleventy is a breath of fresh air and can be learned and made productive in an afternoon.

jerf 5y ago

I recently started using Hugo for a few websites. I endorse this. To give a concrete example, I spent quite a while just figuring out what it means to put a piece of content into a directory under hugo, and I still don't have a full grasp on it, honestly. What does it mean to put something under "content/posts/2011" versus dumping it into content/posts? How exactly do categories and tags get populated? (What is the difference between them?) Something as basic as that has taken me quite a while to get through. (Please note I am not asking for answers to those questions here. In fact dumping the answers here in a nice, clean, easy-to-understand format that walks you through from start to finish would be in some sense actively counterproductive. Go dump them in the Hugo docs!) I can not point you at a specific page that describes the answer to this question. I can not point you at a specific page that describes how we get from content to the various collections of content. This documentation exists, but it's buried in a generic listing that has tons of other stuff, and IIRC still doesn't describe edge cases; I was experimenting with things just to see what they did, because I don't think the docs even acknowledged the edge case. Also, there's a lot of stuff made available in the templates but there's nothing like type-level documentation that says what is of what type and what that type can do; collections of pages will be described almost literally as that, but with no link to exactly what a Page object is. Again, it's probably all there somewhere but it's very hard to use. I mean, technically it's all there, but I certainly had to go on an adventure to get it all. The tutorial also suffers from being too simplified. Tutorials always have this temptation to show off all the magic being used in its simplest possible default configuration, which is fine, but then if you want something other that the simplest possible default configuration you're left with not much to go on. It could be worse, but it certainly has some organizational problems. No matter what problem I come the documentation with, be it looking up what an API does, trying to understand a subsystem, understanding the whole thing holistically, figuring out why I want a certain feature (I almost manually recreated the entire concept of a manual taxonomy before figuring out what it actually meant), the docs just never quite manage to answer my question.

kvnnews 5y ago

I used Hugo for a while and remember their documentation and ultimately the implementation itself was confusing, which then resulted in an overly complex data structure that was hard to modify. Also tried a few other static site generators before just writing my own with python+markdown+jinja+etc.

awill 5y ago

I've been using Hugo for several years. But I'm mostly using freely available templates with minimal changes. Though some of those changes do require a lot of trial and error due to the lacking documentation. Is the competition better? I see a lot of buzz around eleventy. There's also Pelican, Jekyll, Gatsby and many others.

eloff 5y ago

I like Hugo quite a lot, but I don't like Go's standard library templates. I wonder if it is possible to use https://github.com/valyala/quicktemplate https://github.com/valyala/quicktemplate with Hugo?

sreevisakh 5y ago
Zola [1] was created exactly for this reason. It even says so in the Readme. The templates are based on Jinja though, not mako. They also claim that their CLI is intuitive and documentation is good. I certainly found it more comprehensible than Hugo's. [1] https://www.getzola.org/ https://www.getzola.org/
- rimutaka 5y ago
  I switched from Hugo to Zola. Happy as Larry.
- eloff 5y ago
  Nice, thanks for the link, it looks interesting. Implemented in Rust.

cryptos 5y ago

The template engine is not so awesome (it is the Go template engine, really awkward!). Another thing that is really not awesome is that Hugo doesn't use semantic versioning, so that you don't have any idea whether the new version will break your project or not.

yoz-y 5y ago
Once a Hugo update broke my website. So what I did was to take the latest version of the binary, and chugged it in the repo with the site code. Now I just never update. Also helps with the urge to tweak things instead of writing (not that I write much anyways).

quyleanh 5y ago

And so does its themes. It seems that the good UI/UX web designers don't have interest to Hugo theme. I check the Hugo theme site [0], but difficult to find out the good one. Not like some React/Vue community. Here is my wife site [1] with custom Call me Sam theme [2]. Check it out and let see what a hardware designer can do for his wife :) [0] https://themes.gohugo.io/ https://themes.gohugo.io/ [1] https://imblien.com/ https://imblien.com/ [2]https://github.com/victoriadrake/hugo-theme-sam https://github.com/victoriadrake/hugo-theme-sam

vanisher93 5y ago

I mean, I get it, but why not opening a couple of PRs then? It is an open source project after all.

byteski 5y ago

well I figured out how Hugo works only by “clone the existing Hugo theme, change something, see what happens”.

WaitWaitWha 5y ago

I believe we also discussed Hugo here: https://news.ycombinator.com/item?id=30142558 https://news.ycombinator.com/item?id=30142558

dkarl 5y ago

As another poster said, the problem is that Hugo is built around a number of new concepts. To understand them, you have to understand their relation to two contexts: the other Hugo concepts that they are designed to work with, and Hugo's purpose of generating web sites from data. The docs are written almost entirely in the first context, building the concepts up and explaining how they work together, so if you start with the docs you can end up spending a lot of time trying to create a mental model entirely out of these concepts, with no connection to the concrete function of the software.

hugopipes 5y ago

It is too big of an ask to ask a beginner to make a pull request, let alone contribute to Hugo Docs! I have raised close to three issues in the forum about the docs and how straightforward the issues I raised could be made but I was overruled by the mods.

earthboundkid 5y ago

I've made a lot of sites with Hugo, and so I appreciate the Hugo docs as a reference, but I agree that they're not suitable as a tutorial for new users.

recursive 5y ago

Hugo documentation is a monad tutorial.

jordanmorgan10 5y ago

For this precise reason, I use Jekyll. I got so frustrated with Hugo, and when I went to Jekyll they had an entire "From start to finish, make a blog with Jekyll" in their docs. That made all of the difference for me. This was about 3 years ago, so maybe things have changed. But last time I checked, Jekyll still had that guide up.

shadowgovt 5y ago

I've found one of the recommended books very useful for getting started (https://www.manning.com/books/hugo-in-action https://www.manning.com/books/hugo-in-action). But, (a) it's preprint and has copy-editing bugs and (b) it doesn't address the issue of the lack of reference docs.

fmajid 5y ago

It's not ideal, but it is comprehensive. Infinitely superior to the Wordpress or Joomla documentation. It helps the system is less baroque to begin with.

amai 5y ago

Hugo would be a lot more awesome, if they would fix this 7 year old issue : Add ability to generate per-{year, month, day} archives: https://github.com/gohugoio/hugo/issues/448 https://github.com/gohugoio/hugo/issues/448

synergy20 5y ago

I now think rust-based mdbook is simpler and better than hugo, give it a spin. the limit of mdbook is that it's one book only. another one is vitepress(vue3 based but you don't need know vue3 to use vitepress) that you can have multiple 'books' under one site.

throwaway5486nv 5y ago

How could some framework be awesome without having good documentation?

sandreas 5y ago

I pretty much had the same experience. If someone is interested in my personal notes how to get started from scratch with hugo, see https://pilabor.com/blog/2021/05/building-a-blog-with-hugo/ https://pilabor.com/blog/2021/05/building-a-blog-with-hugo/

stonecharioteer 5y ago

I tried Hugo, and Jekyll and my biggest gripe with either is the Markdown format. I prefer RestructuredText and it is truly a superior format. I understand why Markdown is more popular but I can't understand why these static site generators support only Markdown. Sphinx supports both, and I use it everywhere. Paired with Pradyun's Furo theme, it truly is a far better experience.

mbrodersen 5y ago

Writing good documentation is exactly like writing good software: you need to start with a known foundation (the readers prior knowledge/the OS platform) and then build layers of knowledge/software on top of that. One layer at a time. And never have circular dependencies. This is why I recommend only hiring software developers who communicate clearly. Software developers who can’t communicate clearly will write software that is badly structured and hard to maintain. A confused/unclear/unsystematic mind will write confusing/unclear/unsystematic documentation/software.

zwbetz 5y ago

I'm a big hugo fan. I contribute to their forum. I use hugo to build my site. I've used it on freelance projects. I could go on and on about it. I do hear the concerns here. I agree that the docs are more reference style, and less tutorial style. (Tho, as you gain experience, you prefer the reference style). After I learned hugo, I wrote the tutorial I wish I would of had. Am shamelessly sharing it here in case it's useful for someone else wanting to deep dive: https://zwbetz.com/make-a-hugo-blog-from-scratch/ https://zwbetz.com/make-a-hugo-blog-from-scratch/