Thoughts from a new user

feature
1

Having just completed my first site with Hugo, I thought I would sum up some of my thoughts about where I think there’s room for a few tweaks/improvements to help noobs like me to get up and running with Hugo.

  • Variable casing - it’s all over the place. The docs say Camel Case, but it’s not consistent. Front matter is all lowercase, yet config parameters are all an array. Just make it all lowercase (saves having to keep hitting SHIFT).

  • Config/Front Matter format - having support for TOML, YAML and JSON is lovely, but just pick one. It’ll simplify the docs and avoid confusion.

  • Conditionals - Not Hugo’s fault, it’s the Go templating language, but why not use a format everyone is familiar with (i.e. if this condition that then)?

  • Template paths - I’ve primarily built in WordPress before, so I’m biased, but its very confusing. Why all the different folders? Allow people to create a partials folder, have a separate static folder, but everything else should remain at the top level, then simply prefix it with section names to override the default names where necessary (i.e. blog_single.html overrides single.html).

  • Partials - why have partials and .Render? Just stick with partials. And if no context specified, use a default.

  • Functons - usage seems to be all over the place, with some being called using ‘name param1 param2’ and others ‘data | name param’ (if you can do one or other or both, show examples in the docs of each)

  • Options missing from docs - quite a few times I had to search the forum to find out how to do something, a prime example is rssURI (note the lack of Camel Case), which is undocumented. Make it a rule that no feature gets merged unless documented properly.

I’m putting together a ‘tips’ post for those new to Hugo on one of my sites and will review the docs to see where tweaks could make things clearer and easier.

Anyway, didn’t wish to come and complain, I love Hugo, just thought I would throw a cat amongst the pigeons to see if I could stir up some discussion and provide the new guy’s point of view.

3

I’m just a user, so take this for what it’s worth.

  • Variable casing - I agree. It’s a little confusing.
  • Config format - I agree. The docs should use a single format in the examples.
  • Conditionals - I doubt you’ll see Hugo move away from Go templates any time soon. If we supported the Pongo2 template engine, it would probably solve this issue for you, but it probably wouldn’t be the default template engine. Join the fray.
  • Template paths - We’ll have to agree to disagree here.
  • Functions - Agreed. Docs need some love.
  • Missing options - Again, docs need some love.

You do bring up a good point. Requiring docs for new features should be required prior to merge. If not that, we should at least require the creation of a separate release-blocking issue in Github prior to merge.

Thanks for the constructive feedback. Most of your issues revolve around poor or confusing documentation practices. Writing and improving the documentation is one of the easiest ways to give back to Hugo, so everyone is encouraged to help out.

4

Great feedback. Of the obvious, the “casing issue” is something we should just fix – by making every user config case-insensitive.