Comprehensive hugo tutorial for beginners?


Is there any book, MOOC or comprehensive tutorial for Hugo ?

Far too many tutorials are content simply by showing how to create a new site, apply a theme, change the title or whatever and then say “good luck, that’s it !”. The equivalent of showing a hello world program and tells you to peruse the standard library.


Development in Hugo happens fairly rapidly, and sometimes what a site looks like, in code and the way templates change, it can be drastic.

I think that is the main reason there isn’t a book or anything. It would be outdated in a few weeks. There are very few projects I can say that about, too. The devs and contributors are rapid-fire.

That said, I also think that making a new site and understanding the basics of a theme is actually all there is to Hugo. Is there a domain of knowledge or a specific tutorial you are looking for?

For the most part, the tutorials I’ve seen are around how someone set up their site. The hosting companies write about how their platforms host Hugo. Those kinds of things.

Here’s hoping others have better webs than I! :slight_smile:


I’ve written a couple (40+) articles about Hugo here: Hugo tutorials. I haven’t been vocal about it or promote it because I’m not really happy with the format I’ve used and because I’m working on moving everything from that domain to a new one.

Do you have an idea what a “comprehensive tutorial” means to you? That would help me since what someone starting in Hugo wants to read might very well be a different topic than I plan to write about. :slight_smile: So if you have suggestions that would be great!


I guess what I was thinking in terms of tutorials is a walkthrough in creating a website. Probably a non-obvious one like blogging which is very well supported in Hugo.

Perhaps step-by-step in creating an e-commerce or a portfolio site with sprinkled with links for specific areas if the learner wants to have a more in-depth discussion on those topics.


The community organized a number of tutorials but, unfortunately, some weren’t incorporated into most recent overhaul of the docs site but an issue is open to help address that here:

And here are some other resources I pulled out of the docs site GH repo:

@budparr also has a number of items on his site which may be helpful until the above open issue is resolved.


Thanks for the suggestions @klei. :slight_smile:

For a blogging walkthrough you’re probably best off with the Hugo docs ‘Getting Started’. If you Google on moving to hugo static website you’ll also find plenty of case studies that might apply to your situation.

Sprinkled with links for more in-depth information would indeed be very helpful. Unfortunately I don’t know one of those. But if you search through the Hugo docs when you come across something unfamiliar you’ll probably learn a lot. And you’re always welcome to ask here on the forum of course. :slight_smile:

For ecommerce I know of a Snipcart tutorial and Forestry also looked at Snipcart more recently.

From what I can see most of those tutorials on GitHub are the same as those listed on hosting and deployment. And the MathJax tutorial is now here.


While not tutorials, per se, @regis has some terrific pieces on his site about Hugo:


And here’s the page on my site where you’ll find links to 104 articles on Hugo:


I found this tutorial very handy:


I’m planning to do some short screencasts for Indiego, my Hugo starter kit for blogs using modular CSS, gulp frontend workflow and microformats. Will post here when I’ve done them!


I also have some hints & tips on my blog.


I am an absolute beginner. Most of the tutorials center around customizing themes at a granular level. This doesn’t help me. I want to take the default site, change an image or two, add some posts and be done. For instance, I can’t find anywhere how to change out the default Gargoyle picture.

This is one of those cases where the people writing the tutorials are too close to the subject, so they write for other web developers at the API level.

For instance, this tutorial wants to talk about handling 404 or strings. I don’t care about that, I’m not building the site for others.


Thanks for the feedback. I can relate to your line of thought. But I don’t think other tutorials will cover this, because it’s so specific to the theme you’re using. Information on how to change the default Gargoyle picture is something that we should actually find in the theme’s documentation, not in Hugo documentation.


I believe what OP is after is how to build a production site. cornered the market on this somehow for WP even though WordPress was released under GPL. As more Forestries and the like pop up I presume the same will happen for (or to?) Hugo. Hopefully innovations like Docker and Yocto will help people realize you don’t need to pay more than a few pennies a month to host a static website. Meanwhile it would be nice to see more themes providing their own E2E tutorials.


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.

I’ve only just started looking at it but this appears to be the closest thing mentioned here to what I was looking for:


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

Command Line and Text Editor




These look like excellent references… you should add them to the Hugo Documentation. :slightly_smiling_face:

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.

And to highlight the focus.

spf13Hugo Creator

Oct '15

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.


That’s a very nice list. I wish I had it when I was starting out! :laughing: