As a web developer, primarily on the front end, all I can say these days is: Eleventy.
Hugo is awesome, its documentation is not
61–70 of 128 posts
Re: Hugo is awesome, its documentation is not
#62I'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/
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.
Re: Hugo is awesome, its documentation is not
#63It'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 programmi…
> such as the documentation for the Spring framework. Oh god, so true. It doesn't help when it's not a single project, but fifteen hundred different projects (as is the case with spring) and it's impossible to find a coherent documentation beyond the most basic examples.
Right its easier to switch entirely to something else. If you use Micronaut, Microprofile, Vert.x etc your life is much easier.
Re: Hugo is awesome, its documentation is not
#64Earlier quoted context omitted.
> such as the documentation for the Spring framework. Oh god, so true. It doesn't help when it's not a single project, but fifteen hundred different projects (as is the case with spring) and it's impossible to find a coherent documentation beyond the most basic examples.
Right its easier to switch entirely to something else. If you use Micronaut, Microprofile, Vert.x etc your life is much easier.
Micronaut is slowly but surely going in the same direction: dozens if not hundreds separate guides with basic examples.
Re: Hugo is awesome, its documentation is not
#65I 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.
Re: Hugo is awesome, its documentation is not
#66Earlier quoted context omitted.
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…
Django has some of my favourite docs, organized incredibly well: * Tutorials * Topic guides * Reference guides * How-to guides https://docs.djangoproject.com/en/4.0/#how-the-documentation...
Sphinx-based docs are usually excellent due to how easily it lets you flow between tutorials and references.
Re: Hugo is awesome, its documentation is not
#67I 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.
Re: Hugo is awesome, its documentation is not
#68Earlier quoted context omitted.
Django has some of my favourite docs, organized incredibly well: * Tutorials * Topic guides * Reference guides * How-to guides https://docs.djangoproject.com/en/4.0/#how-the-documentation...
Sphinx-based docs are usually excellent due to how easily it lets you flow between tutorials and references.
Sphinx has a nice facility for blending "Javadoc" style documentation with discursive explanations which is used to great effect in the Python docs, but used that way it doesn't automatically generate all of the automatically generatable documentation the way Javadoc does so often you end up with lots of content missing.
Re: Hugo is awesome, its documentation is not
#69I'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.
Re: Hugo is awesome, its documentation is not
#70I 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 with Hugo?