I came here looking for the same thing. While reading the docs I had the same thought as buddha314 - the people writing the docs are too close to the subject matter. There are a ton of details which are great for advanced users, but the higher level info on here’s what Hugo can do and why you might want to customize this or that piece is harder to find. When you don’t have the background information, the details can get kind of overwhelming.
Very sad that the Hugo Experts with the skills to create accurate up to date documentation don’t realize the importance of the new user community in promoting their wonderful product.
The article you referenced is almost 3 years old, and while it may be accurate, it would be better if something like it was part of the official Hugo Documentation ( for new users ).
One way for an expert “too close to the subject matter” to write instructions for a new user is to actually work with them for 20 minutes and ask them to get a site running and produce their first post. I doubt most new users could accomplish the task given the current state of the documentation.
For anyone thinking this is a rarely occurring issue, please consider this topic has had 1.4K views since June. Also, a quick search of this forum shows many frustrated newbies.
When I started using Hugo a number of years ago, the documentation was less well developed than it is now. It has been improved immensely through the hard work of many volunteers. I tried to read everything, and read it again. I don’t think there’s a substitute for that. I had to pester people in here a lot, to try to get the info I needed.
Many of the complaints I see are the result of a) people not knowing the basics of front end web development (not a hugo problem) and/or, simply refusing to read through the docs or search them.
If you see that something’s lacking, please contribute. Even as a Hugo beginner, you can somehow pick through steps to get a basic site running, take notes, and send a pull request to improve the basic tutorials.
That is to say, yes, I agree: there’s always room for improvement.
When I started using hugo, I had no problem getting a basic site up and running by following the docs. As @RickCogley mentioned, read, then re-read. I usually learn something new when I revisit the documentation.
———
If you have things to contribute to the docs, but don’t yet know how, there is never a better time to learn than now. There are many wonderful resources on the web. Here are a few of my favorites
These look like excellent references… you should add them to the Hugo Documentation.
I think if you search the Forum you will find many frustrations from people who take issue with the initial Hugo learning curve. You can argue they don’t have the basic skills, or are too lazy to read and re-read the documentation, but the fact is, they leave and are no longer Hugo proponents. I believe this problem can be fixed by people who have adequate knowledge of Hugo and put together a step by step, copy and paste, start to finish guide. It should not be an effort by newbies to cobble together some notes about what they think they know.
From a recent post:
That said, I do agree with you that the Install Hugo page does need a reorganization. It has been worked on by many different people over time, and it has become somewhat inconsistent, with generic instruction (e.g. compiling from source) misplaced under the macOS-specific instruction, and with various “caveats” removed for the sake of simplicity, but at the cost of sacrificing ease troubleshooting.
We should do more to cater to the beginning web developers/content
creators. We would love help with this. Even just questions beginners have
would be a huge help.
This might come off as facetious, but I want assure everyone: I am being serious.
I don’t think anyone is too lazy, or rather it is certainly rare for a person just wanting to be told what to do to join the forums. Most folks are more likely new to getting remote support, don’t know how to use docs, or maybe are new to web development., but they all want to figure out how to make their website. Let’s talk about that last part, though: “they leave and are no longer Hugo proponents”.
Do we care about that? Do we adjust documentation so anyone, regardless of skill can use Hugo and have a pleasant experience?
I don’t know. Websites are hard, in a general sense. We do weird things and interact with weird services, often in ways that are counter-intuitive. And Hugo embraces the weird parts, because otherwise you could just install WordPress and worry only about the content side.
So let’s hold off drawing a line in the sand immediately. Let’s remain open to embracing all users, and helping them along. How do we do that?
We’re going to need to hire a document engineer to work with everyone committing. They’ll need to track the direction of the project, to know which docs will be changing. They’ll need to work with all the package maintainers, to ensure the install directions remain the same for all users on all platforms, even as we adjust how the extended binary is used. They’ll need to explain the basics of web-based communication, the portion that static site generators participate in, and then how Hugo and golang abstract those concepts in a particular way, but mostly how go templates can’t be used in markdown files…
It’s not where the project is right now. We’ll get there. But our volunteer band will need to either inherit an incredible amount of boring leisure time, or you’ll need to inspire documentation itches that need to be scratched, during this phase of rapid development.
Also, as the project gets more popular, we are going to draw more folks with less experience. That’s numbers. But there are a lot of Hugo sites out there, built by people that don’t actively participate in these forums, and they got through the docs just fine. Let’s be aware of negativity bias while appreciating new user frustration. Let’s not forget the hundreds of support topics solved each month!
As someone only an hour into Hugo, I want to convey how frustrating this conversation is. @maiki’s reply is basically giving excuses for not doing what is obvious: Push the tutorial in the Quick Start guide further, so that the basics of website authoring are covered.
My one-sentence background: I’m in the process of evaluating Hugo as the tool for our “static” (from the server-side) web sites.
Getting Hugo up and running was no problem, and I was able to choose a theme and start writing blog posts by working through the Quick Start guide. Great. Naturally, I wanted to start including images and video. But the next page in the Getting Started series, ignoring the Install Hugo page coming after the Quick Start Guide, goes into the basics of Hugo’s command-line options. No problem, I’ll just skip ahead to where the image and video stuff must be. The problem is that it isn’t obvious where that is. I clicked around a bit, but it was past quitting time. So I gave up and left…and very nearly dropped Hugo.
Luckily, I’m stubborn and picked it up again this morning and decided to check out Mike Dane’s YouTube video that is embedded on the Directory Structure page. At this point, I will work through Mike’s video tutorial series to figure out if Hugo will suit our needs…but I still don’t know how to put images on a page in Hugo.
The solution seems obvious to me. Just push the tutorial in the Quick Start page further. If it covered a basic blog, including images, embedded video, internal/external links, and the more obvious stuff that nearly every website uses, it would be a huge improvement. Instead, the new user is launched into what is basically reference material, and they don’t know enough to know how to navigate that material.
The point of the Quick Start guide is to get the user to the point where they can do something useful and give them a reason to push further. After finishing the Quick Start guide, I can put up a text-only blog. That’s just not enough.
This is low-hanging fruit here. Honestly, every day that this goes unaddressed is a day of delay of Hugo’s adoption.
If I happen to catch Hugo fever and learn the tool properly, I’d be happy to try to push the Quick Start guide further, but I’m not the right person for that at the moment and may never be.
As someone who started just a couple of weeks ago using Hugo I found mike Danes tutorials very useful. Did they answer every question? No ,but it gave me the basic structure that I needed to know how to get started even without using a theme. No matter what you decide to learn there will always be specifics that you’ll have to dig up to personalise your site. I don’t think that’s what a tutorial is for. I admit though that I wish they were more specific sometimes. I think Mike’s tutorial is probably about as low level as you can be and still understand the structure needed to create your own theme, assuming you know some html and css. There were a couple of details left out that I asked in this forum and got answers to. Between that and some Google searches I figured it out, I think. Time will tell, but I’m sure I’ll be back asking more newb questions. I’m not sure if this helps but hang in there and keep asking questions. Respectfully
I’m an experienced with CSS, HTML, JavaScript, C++, Java, shaders, OpenGL and many others. I’m used to learning new stuff. I really like how Hugo is extremely fast and capable. Thank you for creating such a powerful tool!
Unfortunately, every time I need to change something in my site, or create a new site a year after the last time I touched Hugo, I feel stupid and frustrated. I spend days trying things while looking at blank resulting pages with no errors or warnings. It could mean I’m a lousy programmer but I don’t have this issue with other environments. I know that if my job was full time hugo I would not have such issues, but at the moment I do struggle.
I take the time to write this because I care, I want to learn, and I want this great tool to be easier to learn by others
Some thoughts and suggestions about the documentation:
The documentation shows a grid of concepts with two columns. I find that confusing. I don’t know if I should read first the first column and then the second column, or should I read left right left right left right… Ideally I want to read linearly, starting from an overview and then looking at sections that build on top of previous sections. If you have many sections and they all refer to other sections I find it hard to disentangle.
Same issue at Content Management | Hugo There’s 21 “buttons” in that grid. Should I read everything before I start? I miss order. The first article of all is about GPDR (About Hugo > Overview). Is that the first thing I should learn about it?
Lookup order. See Hugo's Lookup Order | Hugo. That page includes massive lists of lookup locations. What should I do with that information? Memorize it? Or if there’s 20 locations a file could be placed at, how do I choose one of them? What’s the purpose of those lists? Also notice how line breaks make the list unreadable:
Themes: many example get you started by choosing a theme. But what if I don’t want a theme? I think a theme makes sense if you are into designing sites for other people, or if you want to reuse your design in many sites. But that’s not the case on any of my sites. I just need a one-off website. So going to the topic of this post: a tutorial would be super useful in this sense. How do I go from nothing to a web site, and the journey from one to the other, which is often not a straight line, but you try things out and make changes along the way, you add features, change, and remove them.
How to work around the fact that many of you are very experienced, which may make it difficult to see things with the eyes of a beginner? Maybe watch someone learn without giving any hints? And this is not necessarily about being a beginner with building websites, css, html or js, but with all the terminology introduced by hugo or other static sites generators (kind, type, archetype, section, format, layout, theme, template, block, list, taxonomy, partial, shortcode, front matter, etc).
Sometimes new features have been introduced that enables a new way of doing things. It would be great that such a feature comes with a tutorial of how to go from the old-way to the new-way, and not only a page in the documentation that describes the new-way. For example I just went from having media inside static into having it inside per-post folders, and it was not straightforward to figure out.
I think the documentation contains all the needed bits and pieces, but is missing a guide about how to learn, the big picture, the process, why to do things in one way or another, suggested approaches, pitfalls… I’m definitely going to check some of those videos mentioned above to see if that fills the blanks.
If it makes you feel any better, this was my experience with Jekyll which was the first static site builder I tried. It is far more sensitive to mistakes than Hugo is.
This is indeed very confusing for beginners. It arises from the incredible flexibility we have in Hugo of course which is also a benefit.
I think the thing to remember is - you almost certainly will never need to know all of this nor ever use it!
What is helpful - and sorry, I can’t remember off the top of my head whether it is already highlighted in the documentation - I think it is? That you only need a tiny subset of all of this unless you inherit someone’s mess or have some complex requirement.
That defines the whole structure of my site. Each uses various partials to make it easier to amend stuff.
The trick is to create a map of the various dependencies so that you don’t loose track over the time periods you mention.
Well, like most people, I started by using someone else’s theme but - as is often the case - quickly realised that I was fighting it rather than it helping. Also, I really wanted to learn Hugo from the ground up and I was struggling to do that looking at 3rd party themes. They have often evolved over time as well so they don’t always use the current best (and simplest) practices which makes them more confusing. How many, for example, still don’t use baseof.html?
So I created my own simple theme. Then you realise that all you are doing is pushing stuff out of your site and down into the theme.
So, if you don’t want to use a theme - don’t! You don’t need one, don’t specify one in your config.
Yes, Hugo continues to evolve rapidly. This is fine while you are in an active development but once that finishes, if you aren’t a web developer, you - like me - are going to lose track of improvements.
All I can say there is to advise you to follow the release announcements and keep an eye on things. While the documentation you mention would be great, I suspect nobody has time to do that given the pace of change.
One other thing. I try to document things that took me a while to learn - I try to write those things up in blog posts so that others can find them. If we all did a bit of this, it would certainly benefit the community as a whole. Of course, if you think up something that you think would improve the core documentation, I’m sure bep would be super interested in it.
This should be on the manual! Maybe there’s an issue of information overload. There’s tons of ways to do things, but how to choose the right one?
I did go and watch the Mike Dane’s videos on YouTube, and I realized what you mentioned: that tiny subset of required files. I had not heard of baseof.html, but with that I’ll be able to remove much redundancy from my site. I would have preferred a 10 minutes condensed video (too many fill-in words) or even a written post (“from zero to a hugo blog in 15 minutes”). But now I understand what was missing. A pity I couldn’t figure it out from the official docs.
I’ve been trying to generate a site using Hugo for a while (over the last 2+ months). This conversation caused me to look at Mike Dane’s videos, which helped some. I agree that the transition from the Quick Start to the details is abrupt and hard for someone starting out.
While studying in a different area of IT I ran into a tutorial which made me think “If only Hugo had a few tutorials like this”, it could really help. The format, the framework, the flow, conclusion and demonstrable results. Great example in my opinion.
A search of the Hugo Forum showed this thread as the first listed among many, showing the need. Many find it very difficult to gain any level of competency quickly enough.
I am thankful to those with the knowledge taking the time to put together their great work.
A very useful Hugo tutorial I don’t believe mentioned in this thread, for new Hugo learners is.
What I will do, if I ever get the time, is to use the built-in Hugo social sharing/microformats function, as is a lot cleaner and more maintenable than using custom partials. And also, add ability to reference multiple images for a post, as this makes sharing to multiple images much easier on different social networks.
Getting started with Hugo is mostly frustrating. I have now been fighting the whole day and when I finally had a first web page with two posts with sections of content and a structure I was planning for, I wanted to change this very ugly white text on black background for code. An impossible thing with ananka as itself uses tachyions. And that’s when you are stuck. Why did you take ananka as the sample theme which is based on other concepts which are not explained further. You start to find that the documentation is only talking about specific topics but there is nothing that explains how thinks are linked together. So I was giving up changing the colors and looked for a different theme. Should be easy, to replace a theme. But was I wrong. First it seemed to pretty work locally but then I wanted to change the default background picture. I’d rather did not try this. It was there, but when I then prepared the webpages for the server it all went wrong. Formatting went berserk on the web server. Then I thought I start again from scratch but this did not help either. I wanted to track the reason for this but I have no clue where to look. Documentation of Hugo will not help, this is a problem of the theme but the themes are mostly not documented.
I don’t think that you will find many starters or beginners that will be happy with Hugo. Too many things that run in the background are efficiently hidden.
The various tutorials are nice but they are specific and don’t explain either how things are connected together.
Also very frustrating are those error messages you get when running hugo telling you that things will be deprecated are out of date and so on.
I will give it another day, and if that does not solve it I will go back to really static web pages using a text editor as I was always doing.
You need to explain more how the layout links with commands, formatting and themes. Just explaining the syntax, the commands, the markup etc on its own is something for hugo experts but not for starters.
Welcome to the forums @cbscpe. It sounds like your frustrations are with CSS, which you would run into no matter which framework you used to build your web site.
Maybe there’s an issue of information overload. There’s tons of ways to do things, but how to choose the right one?
.