Feature: Overall Ease of Use

feature
1

I’ve got my Hugo site running, to the point where I’m just making changes to the content here and there. Overall, it’s good—no, it’s amazing. I love Hugo. I love how it brings a consistent look and navigation to the site, and makes it easy to preview and build on the fly.

What’s been more of a challenge for me is when I try to do something that seems like it should be simple, and it turns out to be really complicated. It should be really easy to go “This page is a topic with subpages, this is a list, this is a blog with posts” and have it just work.

I know, I know “Perhaps it will make sense if I read the docs.” But it doesn’t. I keep looking for a list of page types, or the relationship between layouts and types, or what archetypes are, and it remains confusing.

And even if it weren’t confusing, Hugo doesn’t always behave itself. My site is mostly single pages or groups of pages (not bundles, I don’t know how to use those). One section was a News page, which for a while was working; I had a list of posts ordered by most recent. But then randomly when I got rid of the fake posts and tried to add new ones, the News page itself started acting like an empty post instead of a list. I was unable to fix the problem easily, so I’m not going to have a News section.

So I deleted those files. But guess what? News came back! Not just in public but in content! I had to delete them again. From time to time, a page will regress for some reason. I never know what’s going to happen with my content.

I know there’s a lot of amazing work in this tool, and I especially appreciate the new clarity around the static directory. But the feeling I get working with it is that if I accidentally name something _index instead of index, or vice versa, or somehow end up missing the word “page” in my YAML, or somehow Hugo thinks something is a list vs. a single, I end up with weird behavior. And sometimes the behavior appears to change (like News no longer working but refusing to die).

I don’t know the answer. Heck, my site is kind of working, so I don’t need a response here. But these are some of the challenges I faced along the way.

1 Like
2

I understand your whole post, but I guess this is inherent to any coding language.
Mistakes and typos create bugs/wrong behaviours.

3

Let me say again: Hugo is amazing. I have a great website thanks to Hugo and one of the many cool themes.

Hugo is not a coding language.

I am a programmer. If I wanted to use a coding language to make a website, I’d use something like PHP or Node. In fact, I have a couple websites running right now on hand-built PHP. I even have a workflow where I can use Markdown to add a page. I’m not the greatest coder in the world, and my skills are a little outdated, but I am familiar with tracking down bugs. Hugo is not a programming language. It is a powerful static site generation framework. It is a collection of different things. It is not a programming language.

Who is the target market for Hugo? Programmers, or content designers?

I understand your whole post, but I guess this is inherent to any coding language.
Mistakes and typos create bugs/wrong behaviours.

I didn’t make a mistake or a typo. index and _index (as you know) have two different intended behaviors. The trouble is that telling a page to be a list, or a bundle, or a single, or whatever, doesn’t involve just one thing. You have to do several things. In a programming language, I can instantiate the class I want with one call. I don’t have to also add something to some YAML and rename the index file. If Hugo were a programming language, I could say “Give me a list page right here.” One step.

I had a section for posts. I had a couple fake posts in there to make sure it worked. I got rid of the fake posts and added my first new real post. That section broke. That’s no typo. What I did is something that many, many people would do. Put a placeholder page or two in, then take it out when real content is ready.

I don’t know how that broke my section. Something weird about my environment? Something else I did along the way? Maybe. Probably my fault. But it should be harder to make mistakes. Hugo is not a programming language, but if it were, it would be easier. Programming languages try to make it hard to make mistakes. Yes, even the hard ones do. The point is productivity, not proving that you don’t make typos. That’s why, with a programming language, you get a compiler warning or an error message when you do something that might be a mistake. Maybe Hugo needs better error messaging.

If it were up to me, I would think the target audience for Hugo is people from the somewhat technical (knows React, but just wants to stand up a website quickly) to the less technical (deciding whether to use SquareSpace or not). And for those people, Hugo has to be easier.

I don’t work on the Hugo project, so I could be wrong. But I think “this is inherent to any coding language” is not the answer. Hugo is not a coding language.

4

I agree that Hugo has a learning curve, specially for people like me that before Hugo, wasn’t familiarized with Go, which you really need at least a grasp of it to work with template files.

However, coming from another static generators, I could say for sure that for me it hasn’t been that hard to learn the basics and a little more.

I have not had that problem, even without the --gc and --cleanDestinationDir flags, but you could try those flags when building your site.

1 Like
5

Hugo has a rather steep learning curve. I had many false starts trying to learn Hugo. Although the documentation is quite thorough, it is not that good at taking you by the hand and guide you through the basics. I have heard the same sentiment from others, too.

I recently discovered an excellent method to organize documentation, and I recommend everyone to have a look at it! Introduction — Documentation system documentation

overview
overview1516×853 125 KB

Hugo’s documentation do have a little bit of everything mixed together, but is generally lacking in the “tutorial” and “how-to” space. By separating the content into these four categories my guess is that newcomers would have an easier time.

I have started writing up something that could fit in the “tutorial” category, taking you by the hand and explaining just enough of the basics to get a taste of how it works. It is just a rough sketch at this point, but I was writing it for my blog (which is not yet published).

What do you think about this way of organizing documentation?

5 Likes
6

I like the “how-to” and “tutorial” approach.

I’ll respond to points in both the above posts…

Go, which you really need at least a grasp of it to work with template files.

Maybe. I’m familiar with Handlebars, and I have worked with other templating systems. I would agree that templates can be confusing, but I’d also counter by saying that for building a basic website maybe you don’t have to do much to the templates, if anything. Oh, there’s a template called “single” that looks like this? Cool. I’ll use it and see if I even need to modify it at all.

Some other static generators are difficult (I think Jekyll has some tricky aspects). Some are easy (MkDocs is remarkably easy). In the early 1900s, driving a car was ridiculously complicated. There’s nothing good or bad about being complicated, and I think Hugo has to remain complicated—where its power comes from—but must also get easier to use.

I recently discovered an excellent method to organize documentation, and I recommend everyone to have a look at it! Introduction — Documentation system documentation

This is excellent. I agree with the major points: documentation has to have these categories. I agree that the Hugo docs are light on the how-to and tutorial content. I also couldn’t find (doesn’t mean it’s not there, but I couldn’t find it) a place that says “If you want page type X, and you want it to behave in way Y, make sure you’ve done the following Z things.”

Here’s the front page:

If you already know Hugo, it’s a very sensible way to organize things. If you don’t, it’s hard to know what’s important at the start. Do I care about lookup? Templating? Commenting? What do I care about first?

It would be really cool to have a journey that looks like:

  • Get started, hello world ← this already exists and is pretty good
  • Tutorial: create a website with various sections ← not much there
  • How to (various common tasks) ← not much there
  • How Hugo thinks about things ← this exists and is well organized but not always informative
  • Reference ← this is spotty
  • Troubleshooting ← this is not comprehensive

I think if you read the entire doc set, every single page, you’ll get the idea. But I mean the entire doc set. It would be nice to know just enough, get up and running, and then learn more as we need to.

Even if you read every page, the content is not always complete. Examples:

  • Would be good to have a full list of content types at Content types | Hugo
  • Content organization | Hugo doesn’t say what a page bundle actually is.
  • Under the Index Pages: _index.md section, it says " _index.md has a special role in Hugo. It allows you to add front matter and content to your list templates." But it doesn’t say anything more about how it works, what it affects, or what the alternatives are.
  • Would be super great to have examples for the most common (or most difficult) things.

TL;DR: Would be nice to have at least “To make a section with an index page, do XYZ; to add a blog section, do ABC; to make a page bundle, which groups static stuff and pages together, do PDQ.”

2 Likes
7

Oh, thanks for this tip btw. But I mean my config.toml even regressed and added my menu for that section back. So it wasn’t just that the subdirectory was there; it was that it got re-added to the nav after I deleted it too.

8
2 Likes
9

Love it.