Comprehensive hugo tutorial for beginners?


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!

Right back at ya! :slight_smile:


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.


Content uses Markdown. So let’s say you wanted to include an image from your static/ folder:

![alt text](path/to/image.jpg)

You can also write HTML directly inside your Markdown.

If you wanted to store your images in the same folder as your post, you could access them as page resources by using shortcodes.

For tutorials and tips n tricks outside the docs, checkout:


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 struggled already 4 years ago:

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 :slight_smile:

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 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 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! :slight_smile: 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.

I’ll post my issue as a new topic.


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.