Comprehensive hugo tutorial for beginners?

[maiki]

This might come off as facetious, but I want assure everyone: I am being serious.

@mojoa

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 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!

@mojoa

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

Right back at ya!

[Mark]

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.

[zwbetz]

@Mark

Naturally, I wanted to start including images and video

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:

• the “hugo tutorials” section of the recommended reading
• the awesome hugo list

[Prophoss]

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

[hamoid]

I struggled already 4 years ago:

Creating a minimal working template

Thank you! Without tutorials like this one I feel that learning Hugo is like learning how to write by looking up words in a dictionary (the official docs) or by looking at a finished novel (sample sites). I need to see the process to understand and learn: start from scratch, write a working hello-world site (without any copy-pasting or templates), then add new features, change the behaviour, and explain how and why I should do things in a certain way. I would be very happy to read or watch mor…

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 Template 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.

[TotallyInformation]

@hamoid

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.

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.

@hamoid

Lookup order

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.

layouts
   _default
      baseof.html
      list.html
      single.html

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.

@hamoid

Themes

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.

@hamoid

new way of doing things

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.

[hamoid]

@TotallyInformation

you almost certainly will never need to know all of this nor ever use 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.

[Leo_Merkel]

Learning Static Site Building with Hugo

[Warren]

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.

[mojoa]

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.

Building Serverless Python Apps Using AWS Chalice – Real Python

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.

https://discourse.gohugo.io/search?q=tutorial

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.

Tutorial: Make a Hugo blog from scratch

Copied from the tutorial intro: In my opinion, Hugo’s current quick start is ample. It does just what the name says, gets you started you quickly . Still, there have many requests on the forums for a tutorial that dives deeper than the quick start, and gets into some templating basics. The thing you’re reading is my go at that. Starting from scratch, we’ll build a Hugo blog. For the folks out there thinking, “just show me the money already”, here’s the finished product source code and demo. …

[Shiva]

Hi,

I checked out your starter kit. Looks good. Do you have any plans to integrate or autogenerate AMP versions of posts ?

I see a lot of blogs that show up on google front page have the amphtml doc generated, and linked in their meta.

Make your page discoverable – AMP

[growdigital]

Thank you .

No plans to do any more work I’m afraid, I’m a full-time forest gardener now https://www.forestgarden.wales/

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.

[cbscpe]

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.

[zwbetz]

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.

[cbscpe]

It has nothing to do with CSS. Its just I don’t find the place where to change it. Everthing is try and error and many times I had to look at the generated files to in order to learn which file was taken by Hugo and where it was applied. It’s like reverse engineering the logic of Hugo. Your documentation gives a great detail about every detailed aspect, but I’m missing the picture, the philosophy of the data structure. Its’ more a glossary than a document. And when you look up a certain topic, even when it is at the top of a chapter, you directly jump into the deep technics. There is now “how to”, there is no “why” and you expect that users of Hugo are familiar with a whole bunch of other applications. There is a huge gap between getting started and the rest. Getting started is easy but then I was immediately lost when reading further. I would say the frustration started with this gap. Also reading the forum is frustrating. I used search, found happily several topics related to my questions and then read the thread, but most answers are unintuitive, or just give a link to the documentation, which in my cases did not answer my questions.
And it also shows that Hugo has evolved over years. A lot of threads, documents and tutorial you find are no longer relevant, because it is outdated, which is very confusing. E.g. there is this Hugo 0.32 How-To in the documentation. How relevant is it to the current release. It says “This documentation belongs in other places in this documentation site, but is put here first … to get something up and running fast.” what do you want to say with this?

[cbscpe]

I gave it another day. And it’s confirmed. Nothing to do with CSS. However the conclusion is still the same, there is a rather large gap between the Quick Start and the next step. You should add something which I call primer. In other words explain how you do something in Hugo when you want to achieve a certain goal. Visual hands-on examples. Like the blogs of zwbetz which I really enjoyed and which helped a lot more than the finger pointing to document chapters. You don’t have to always show the complete picture of Hugo’s capability. You need to relate more often the chapters in the documentation with real examples. The very extensive documentation of Hugo reminds me too much to the old days of IBM hosts with the large sets of paper documents. You really had to read them all at that time to get something running smoothly. I didn’t like it then and I don’t like this format now. You should take more care about non-developers.

[zwbetz]

Is there a specific example of a “primer” you wish existed? I like to keep tutorial ideas in my back pocket

[cbscpe]

Difficult to say. There are many things I need to find out myself and so far I think I’m getting the picture. One question however I have asked myself and did not find any answers that made it clear to me is how to build hiearchical static pages with appropriate navigation. E.g. with the hamburg theme you have blogs and then you have menus for static pages. Now I wanted to make some of the menus to point to another list of pages from which you can individually select pages, if possible with even more hierarchical levels like files and folders, and at the top a navigation bar should appear to make it possible to go back within the tree you have gone down. Like the “Home” button that apears when you have selected one level. I was reading about page bundels and thought that was giving the necessary grid, but up to now all variants I have tried (using _index.md at various levels with folders etc.) did not really match what I had in mind.
Another “mystery” that I have not yet fully discovered is where does Hugo start (file wise) and how the various directories and files are used. There is some info in the doc but I have not found an overview. Something I could print out and then navigate through while editing and adding files, as a newby you often loose track of what was clear only a few hours ago and having some sort of “bullet points” would speed the process, else I have always to go back and read again. Perhaps this is specific to my way of approaching new topics.

[oodavid]

I think the first learning curve is around language / nomenclature.

Hugo is fantastic for using accurate terms such as archetype and taxonomy - while laudable, they’re unusual for anyone coming to this with a background in front-end code (frameworks aside - HTML, CSS and Javascript don’t use these concepts).

I reckon the second is the “lookup order”. This is hard for first-time users as we’re encouraged to start with a theme, my first question was “why does the theme have the same structure as the root folder?” - personally I would have found it easier for themes to reveal themselves after playing with a themeless site. I don’t use themes in any of my sites.

[cbscpe]

Indeed. Perhaps a quick start guide without a theme would be more appropriate as it would reveal more of how Hugo works internally.